diff options
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/eclipse-adt.jd | 500 | ||||
| -rw-r--r-- | docs/html/guide/developing/other-ide.jd | 487 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/aidl.jd | 62 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/avd.jd | 504 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/emulator.jd | 267 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/index.jd | 33 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/othertools.jd | 64 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/traceview.jd | 45 |
9 files changed, 1481 insertions, 909 deletions
diff --git a/docs/html/guide/developing/app-signing.jd b/docs/html/guide/developing/app-signing.jd deleted file mode 100644 index 582dfb2..0000000 --- a/docs/html/guide/developing/app-signing.jd +++ /dev/null @@ -1,428 +0,0 @@ -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/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd index 8c482ee..75f3d78 100644 --- a/docs/html/guide/developing/eclipse-adt.jd +++ b/docs/html/guide/developing/eclipse-adt.jd @@ -1,193 +1,393 @@ -page.title=In Eclipse, with ADT +page.title=Developing 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> +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#CreatingAProject">Creating an Android Project</a></li> + <li><a href="#Running">Running Your Application</a> + <ol> + <li><a href="#CreatingAnAvd">Creating an AVD</a></li> + <li><a href="#RunningAnApplication">Running an application</a></li> + </ol> + </li> + <li><a href="#RunConfig">Creating a Custom Run Configuration</a></li> + <li><a href="#Signing">Setting Up Application Signing</a></li> + <li><a href="#Tips">Eclipse Tips</a></li> + </div> +</div> + + +<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 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> + <li>It provides an Android code editor that helps you write valid XML for your Android +manifest and resource files.</li> + <li>It will even export your project into a signed APK, which can be distributed to users.</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>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.5_r1/installing.html#installingplugin">Installing +the ADT Plugin</a>.</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> +<p>If you are already developing applications using a version of ADT earlier than 0.9, make +sure to upgrade to the latest version before continuing. See the guide to +<a href="{@docRoot}sdk/1.5_r1/upgrading.html#UpdateAdt">Update Your Eclipse ADT Plugin</a>.</p> -<a name="creatingaproject" id="creatingaproject"></a> +<p class="note"><strong>Note:</strong> This guide assumes you are using the latest version of +the ADT plugin (0.9). While most of the information covered also applies to previous +versions, if you are using an older version, you may want to consult this document from +the set of documentation included in your SDK package (instead of the online version).</p> -<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> +<h2 id="CreatingAProject">Creating an Android Project</h2> -<a name="existingcode"></a> +<p>The ADT plugin provides a New Project Wizard that you can use to quickly create a new +Android project (or a project from existing code). To create a new project:</p> <ol> - <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong></li> - <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and 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> - + <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong>.</li> + <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and click + <strong>Next</strong>.</li> + <li>Select the contents for the project: + <ul> + <li>Enter a <em>Project Name</em>. This will be the name of the folder where your + project is created.</li> + <li>Under Contents, select <strong>Create new project in workspace</strong>. + Select your project workspace location.</li> + <li>Under Target, select an Android target to be used as the project's Build Target. + The Build Target + specifies which Android platform you'd like your application built against. + <p>Unless you know that you'll be using new APIs introduced in the latest SDK, you should + select a target with the lowest platform version possible, such as Android 1.1.</p> + <p class="note"><strong>Note:</strong> You can change your the Build Target for your + project at any time: Right-click the project in the Package Explorer, select + <strong>Properties</strong>, select <strong>Android</strong> and then check + the desired Project Target.</p> + </li> + <li>Under Properties, fill in all necessary fields. <ul> - <li>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> + <li>Enter an <em>Application name</em>. This is the human-readable title for your + application — the name that will appear on the Android device.</li> + <li>Enter a <em>Package name</em>. This is the package namespace (following the same rules + as for packages in the Java programming language) where all your source code + will reside.</li> + <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name + for your main Activity class.</li> + <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates + the minimum API Level required to properly run your application. + Entering this here automatically sets the <code>minSdkVersion</code> attribute in the + <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> + of your Android Manifest file. If you're unsure of the appropriate API Level to use, + copy the API Level listed for the Build Target you selected in the Target tab.</li> </ul> - + </li> + </ul> + </li> + <li>Click <strong>Finish</strong>.</li> </ol> -<a name="launchconfig" id="launchconfig"></a> +<p class="note"><strong>Tip:</strong> +You can also start the New Project Wizard from the <em>New</em> icon in the toolbar.</p> + +<p>Once you complete the New Project Wizard, ADT creates the following +folders and files in your new project:</p> + <dl> + <dt><code>src/</code></dt> + <dd>Includes your stub Activity Java file. All other Java files for your application + go here.</dd> + <dt><code><em><Android Version></em>/</code> (e.g., <code>Android 1.1/</code>)</dt> + <dd>Includes the <code>android.jar</code> file that your application will build against. + This is determined by the build target that you have chosen in the <em>New Project + Wizard</em>.</dd> + <dt><code>gen/</code></dt> + <dd>This contains the Java files generated by ADT, such as your <code>R.java</code> file + and interfaces created from AIDL files.</dd> + <dt><code>assets/</code></dt> + <dd>This is empty. You can use it to store raw asset files. See + <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> + <dt><code>res/</code></dt> + <dd>A folder for your application resources, such as drawable files, layout files, string + values, etc. See + <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> + <dt><code>AndroidManifest.xml</code></dt> + <dd>The Android Manifest for your project. See + <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml + File</a>.</dd> + <dt><code>default.properties</code></dt> + <dd>This file contains project settings, such as the build target. This files is integral + to the project, as such, it should be maintained in a Source Revision Control system. + It should never be edited manually — to edit project properties, + right-click the project folder and select "Properties".</dd> + </dl> + + +<h2 id="Running">Running Your Application</h2> + +<p><em>Wait!</em> Before you can run your application on the Android Emulator, +you <strong>must</strong> create an Android Virtual Device (AVD). +An AVD is a configuration that specifies the Android platform to be used on the emulator. +You can read more about AVDs in the <a href="{@docRoot}guide/developing/index.html#avd">Developing +Overview</a>, but if you just want to get started, follow the simple guide below to create +an AVD.</p> + +<p>If you will be running your applications only on actual device hardware, you do not +need an AVD — see +<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> for information +on running your applicaiton.</p> + +<h3 id="CreatingAnAvd">Creating an AVD</h3> + +<p>To avoid some explanation that's beyond the scope of this document, here's the +basic procedure to create an AVD:</p> -<h2>Creating a Launch Configuration </h2> +<ol> + <li>Open a command-line (e.g.,"Command Prompt" application on Windows, or "Terminal" + on Mac/Linux) and navigate to your SDK package's + <code>tools/</code> directory.</li> + <li>First, you need to select a Deployment Target. To view available targets, execute: + <pre>android list targets</pre> + <p>This will output a list of available Android targets, such as:</p> +<pre> +id:1 + Name: Android 1.1 + Type: platform + API level: 2 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:2 + Name: Android 1.5 + Type: platform + API level: 3 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +</pre> + <p>Find the target that matches the Android platform upon which you'd like + to run your application. Note the integer value of the <code>id</code> — + you'll use this in the next step.</p> + </li> + <li>Create a new AVD using your selected Deployment Target. Execute: + <pre>android create avd --name <em><your_avd_name></em> --target <em><targetID></em></pre> + <li>Next, you'll be asked whether you'd like to create a custom hardware profile. + If you respond "yes," you'll be presented with a series of prompts to define various aspects of the + device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise, + press return to use all default values ("no" is the default).</li> + </li> +</ol> -<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>That's it; your AVD is ready. In the next section, you'll see how the AVD is used +when launching your application on an emulator.</p> -<p>To create a launch configuration for the application, follow these steps as appropriate for your Eclipse version:</p> +<p>To learn more about creating and managing AVDs, please read the +<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> +documentation.</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> +<h3 id="RunningYourApplication">Running your application</h3> -</ol> +<p class="note"><strong>Note:</strong> Before you can run your application, be sure that +you have created an AVD with a target that satisfies your application's Build Target. +If an AVD cannot be found that meets the requirements of your Build Target, you will see +a console error telling you so and the launch will be aborted.</p> +<p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or +<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse main menu. The ADT plugin +will automatically create a default launch configuration for the project.</p> -<h2 id="sign_in_adt">Setting Up Application Signing</h2> +<p>When you choose to run or debug your application, Eclipse will perform the following:</p> -<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> +<ol> + <li>Compile the project (if there have been changes since the last build).</li> + <li>Create a default launch configuration (if one does not already exist for the project).</li> + <li>Install and start the application on an emulator or device (based on the Deployment Target + defined by the run configuration). + <p>By default, Android application run configurations use an "automatic target" mode for + selecting a device target. For information on how automatic target mode selects a + deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual + target modes</a> below.</p> + </li> +</ol> -<p>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>If debugging, the application will start in the "Waiting For Debugger" mode. Once the +debugger is attached, Eclipse will open the Debug perspective.</p> + +<p>To set or change the launch configuration used for your project, use the launch configuration manager. +See <a href="#launchconfig">Creating a Launch Configuration</a> for information.</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> +<h2 id="RunConfig">Creating a Run Configuration</h2> -<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>The run configuration specifies the project to run, the Activity +to start, the emulator options to use, and so on. When you first run a project +as an <em>Android Application</em>, ADT will automatically create a run configuration. +The default run configuration will +launch the default project Activity and use automatic target mode for device selection +(with no preferred AVD). If the default setting don't suit your project, you can +customize the launch configuration or even create a new.</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> +<p>To create or modify a launch configuration, follow these steps as appropriate +for your Eclipse version:</p> +<ol> + <li>Open the run configuration manager. + <ul> + <li>In Eclipse 3.3 (Europa), select <strong>Run</strong> > + <strong>Open Run Dialog</strong> (or <strong>Open Debug Dialog</strong>) + </li> + <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> + <strong>Run Configurations</strong> (or + <strong>Debug Configurations</strong>) + </li> + </ul> + </li> + <li>Expand the <strong>Android Application</strong> item and create a new + configuration or open an existing one. + <ul> + <li>To create a new configuration: + <ol> + <li>Select <strong>Android Application</strong> and click the <em>New launch configuration</em> + icon above the list (or, right-click <strong>Android Application</strong> and click + <strong>New</strong>).</li> + <li>Enter a Name for your configuration.</li> + <li>In the Android tab, browse and select the project you'd like to run with the + configuration.</li> + </ol> + <li>To open an existing configuration, select the configuration name from the list + nested below <strong>Android Application</strong>.</li> + </ul> + </li> + <li>Adjust your desired launch configuration settings. + <p>In the Target tab, consider whether you'd like to use Manual or Automatic mode + when selecting an AVD to run your application. + See the following section on <a href=#AutoAndManualModes">Automatic and manual target + modes</a>).</p> + </li> +</ol> -<a name="installingrunningdebugging" id="installingrunningdebugging"></a> -<h2>Running and Debugging an Application</h2> +<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3> -<p>Once you've set up the project and launch configuration for your application, you can run or debug it as described below.</p> +<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to select +an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p> -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> +<ol> + <li>If there's a device or emulator already running and its AVD configuration + meets the requirements of the application's build target, the application is installed + and run upon it.</li> + <li>If there's more than one device or emulator running, each of which meets the requirements + of the build target, a "device chooser" is shown to let you select which device to use.</li> + <li>If there are no devices or emulators running that meet the requirements of the build target, + ADT looks at the available AVDs. If one meets the requirements of the build target, + the AVD is used to launch a new emulator, upon which the application is installed and run.</li> + <li>If all else fails, the application will not be run and you will see a console error warning + you that there is no existing AVD that meets the build target requirements.</li> +</ol> -<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>However, if a "preferred AVD" is selected in the run configuration, then the application +will <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator +will be launched.</p> -<p>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>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" +is presented every time that your application is run, so that you can select which AVD to use.</p> -<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="Signing">Signing your Applications</h2> +<p>As you begin developing Android applications, understand that all +Android applications must be digitally signed before the system will install +them on an emulator or an actual device. There are two ways to do this: +with a debug key (for immediate testing on an emulator or development device) +or with a private key (for application distribution).</p> -<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> +<p>The ADT plugin helps you get started quickly by signing your .apk files with +a debug key, prior to installing them on an emulator or development device. This means that you can +quickly run your application from Eclipse without having to +generate your own private key. No specific action on your part is needed, +provided ADT has access to Keytool.However, please note that if you intend +to publish your application, you <strong>must</strong> sign the application with your +own private key, rather than the debug key generated by the SDK tools.</p> + +<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides a thorough guide to application signing on Android +and what it means to you as an Android application developer. The document also includes +a guide to exporting and signing your application with the ADT's Export Wizard.</p> + + +<h2 id="Tips">Eclipse Tips </h2> + +<h3 id="arbitraryexpressions">Executing arbitrary Java expressions in Eclipse</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> + + +<!-- TODO: clean this up and expand it to cover more wizards and features +<h3>ADT Wizards</h3> + +<p>Notice that the "New Android Project" wizard has been expanded to use the multi-platform +capabilities of the new SDK.</p> + +<p>There is now a "New XML File" wizard that lets you create skeleton XML resource +files for your Android projects. This makes it easier to create a new layout, a new menu, a +new strings file, etc.</p> + +<p>Both wizards are available via <strong>File > New</strong> and new icons in the main +Eclipse toolbar (located to the left of the Debug and Run icons). +If you do not see the new icons, you may need to select <strong>Window > Reset +Perspective</strong> from the Java perspective.</p> +--> diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd index 7bcb509..8cdf0b9 100644 --- a/docs/html/guide/developing/other-ide.jd +++ b/docs/html/guide/developing/other-ide.jd @@ -1,167 +1,408 @@ -page.title=In Other IDEs +page.title=Developing In Other IDEs @jd:body +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#CreatingAProject">Creating an Android Project</a></li> + <li><a href="#Signing">Preparing to Sign Your Application</a></li> + <li><a href="#Building">Building Your Application</a> + <ol> + <li><a href="#DebugMode">Building in debug mode</a></li> + <li><a href="#ReleaseMode">Building in release mode</a></li> + </ol> + </li> + <li><a href="#Running">Running Your Application</a></li> + <li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> + <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> + <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></li> + </ol> +</div> +</div> + <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> +<a href="{@docRoot}guide/developing/eclipse-adt.html">Eclipse with the ADT plugin</a>. +The ADT plugin provides editing, building, debugging, and .apk packaging and signing 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> +<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, +or in a basic editor, such as Emacs, you can do that instead. The SDK +includes all the tools you need to set up an Android project, build it, debug it and then +package it for distribution. This document is your guide to using these tools.</p> -<h2>Creating an Android Project </h2> +<h2 id="EssentialTools">Essential Tools</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>When developing in IDEs or editors other than Eclipse, you'll require +familiarity with the following Android SDK tools:</p> -<p>To run <code>activityCreator</code> and create an Android project, follow these steps:</p> +<dl> + <dt><a href="{@docRoot}guide/developing/tools/othertools.html#android">android</a></dt> + <dd>To create/update Android projects and to create/move/delete AVDs.</dd> + <dt><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></dt> + <dd>To run your Android applications on an emulated Android platform.</dd> + <dt><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></dt> + <dd>To interface with your emulator or connected device (install apps, + shell the device, issue commands, etc.). + </dd> +</dl> + +<p>In addition to the above tools, included with the SDK, you'll use the following +open source and third-party tools:</p> + +<dl> + <dt>Ant</dt> + <dd>To compile and build your Android project into an installable .apk file.</dd> + <dt>Keytool</dt> + <dd>To generate a keystore and private key, used to sign your .apk file.</dd> + <dt>Jarsigner (or similar signing tool)</dt> + <dd>To sign your .apk file with a private key generated by keytool.</dd> +</dl> + +<p>In the topics that follow, you'll be introduced to each of these tools as necessary. +For more advanced operations, please read the respective documentation for each tool.</p> + + +<h2 id="CreatingAProject">Creating an Android Project</h2> + +<p>To create an Android project, you must use the <code>android</code> tool. When you create +a new project with <code>android</code>, it will generate a project directory +with some default application files, stub files, configuration files and a build file.</p> -<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: +<h3 id="CreatingANewProject">Creating a new Project</h3> + +<p>If you're starting a new project, use the <code>android create project</code> +command to generate all the necessary files and folders.</p> + +<p>To create a new Android project, open a command-line, +navigate to the <code>tools/</code> directory of your SDK and run:</p> +<pre> +android create project \ +--target <em><targetID></em> \ +--path <em>/path/to/your/project</em> \ +--activity <em><your_activity_name></em> \ +--package <em><your_package_namespace></em> +</pre> + <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> + <li><code>target</code> is the "build target" for your application. It corresponds + to an Android platform library (including any add-ons, such as Google APIs) that you would like to + build your project against. To see a list of available targets and their corresponding IDs, + execute: <code>android list targets</code>.</li> + <li><code>path</code> is the location of your project directory. If the directory does not exist, + it will be created for you.</li> + <li><code>activity</code> is the name for your {@link android.app.Activity} class. This class file + will be created for you inside + <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>.</li> + <li><code>package</code> is the package namespace for your project, following the same rules as for + packages in the Java programming language.</li> </ul> -</li> -</ol> -<p>Here's an example:</p> +<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> +android create project \ +--target 1 \ +--path ./myProject \ +--activity MyActivity \ +--package com.example.myproject +</pre> -<p>The <code>activityCreator</code> script generates the following files and directories (but will not overwrite existing ones):</p> +<p>The tool generates the following files and directories:</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> + <li><code>AndroidManifest.xml</code> - The application manifest file, + synced to the specified Activity class for the project.</li> + <li><code>build.xml</code> - Build file for Ant.</li> + <li><code>default.properties</code> - Properties for the build system. <em>Do not modify + this file</em>.</li> + <li><code>build.properties</code> - Customizable properties for the build system. You can edit this + file to overried default build settings used by Ant.</li> + <li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class + you specified during project creation.</li> + <li><code>bin/</code> - Output directory for the build script.</li> + <li><code>gen/</code> - Holds <code>Ant</code>-generated files, such as <code>R.java</code>. </li> + <li><code>libs/</code> - Holds private libraries.</li> + <li><code>res/</code> - Holds project resources.</li> + <li><code>src/</code> - Holds source code.</li> + <li><code>tests/</code> - Holds a duplicate of all-of-the-above, for testing purposes.</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> +<p>Once you've created your project, you're ready to begin development. +You can move your project folder wherever you want for development, but keep in mind +that you must use the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> +(adb) — located in the SDK <code>tools/</code> directory — to send your application +to the emulator (discussed later). So you need access between your project solution and +the <code>tools/</code> folder.</p> + +<p class="warning"><strong>Note:</strong> You should refrain from moving the +location of the SDK directory, because this will break the build scripts. (They +will need to be manually updated to reflect the new SDK location before they will +work again.)</p> + -<h2 id="sign_in_other">Setting Up Application Signing</h2> +<h3 id="UpdatingAProject">Updating a project</h3> -<p>As you begin developing Android applications, you should understand that all +<p>If you're upgrading a project from an older version of the Android SDK or want to create +a new project from existing code, use the +<code>android update project</code> command to update the project to the new development +environment. You can also use this command to revise the build target of an existing project +(with the <code>--target</code> option). The <code>android</code> tool will generate any files and +folders (listed in the previous section) that are either missing or need to be updated, +as needed for the Android project.</p> + +<p>To update an existing Android project, open a command-line +and navigate to the <code>tools/</code> directory of your SDK. Now run:</p> +<pre> +android update project --target <em><targetID></em> --path <em>path/to/your/project/</em> +</pre> + +<ul> + <li><code>target</code> is the "build target" for your application. It corresponds to + an Android platform library (including any add-ons, such as Google APIs) that you would + like to build your project against. To see a list of available targets and their corresponding IDs, + execute: <code>android list targets</code>.</li> + <li><code>path</code> is the location of your project directory.</li> +</ul> + +<p>Here's an example:</p> +<pre> +android update project --target 2 --path ./myProject +</pre> + + +<h2 id="Signing">Preparing to Sign Your Application</h2> + +<p>As you begin developing Android applications, understand that all Android applications must be digitally signed before the system will install -them on the emulator or an actual device. </p> +them on an emulator or device. There are two ways to do this: +with a <em>debug key</em> (for immediate testing on an emulator or development device) +or with a <em>private key</em> (for application distribution).</p> -<p>The Android build tools help you get started quickly by signing your .apk -files with a debug key, prior to installing them on the emulator. This means +<p>The Android build tools help you get started by automatically signing your .apk +files with a debug key at build time. This means that you can compile your application and install it on the emulator without having to generate your own private key. However, please note that if you intend -to publish your application, you <em>must</em> sign the application with your +to publish your application, you <strong>must</strong> sign the application with your own private key, rather than the debug key generated by the SDK tools. </p> -<p>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> +<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides a thorough guide to application signing on Android +and what it means to you as an Android application developer.</p> + + + +<h2 id="Building">Building Your Application</h2> + +<p>There are two ways to build your application: one for testing/debugging your application +— <em>debug mode</em> — and one for building your final package for release — +<em>release mode</em>. As described in the previous +section, your application must be signed before it can be installed on an emulator +or device.</p> + +<p>Whether you're building in debug mode or release mode, you +need to use the Ant tool to compile and build your project. This will create the .apk file +that is installed onto the emulator or device. When you build in debug mode, the .apk +file is automatically signed by the SDK tools with a debug key, so it's instantly ready for installation +(but only onto an emulator or attached development device). +When you build in release mode, the .apk file is <em>unsigned</em>, so you must manually +sign it with your own private key, using Keytool and Jarsigner.</p> + +<p>It's important that you read and understand +<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>, particularly +once you're ready to release your application and share it with end-users. That document describes +the procedure for generating a private key and then using it to sign your .apk file. +If you're just getting started, however, +you can quickly run your applications on an emulator or your own development device by building in +debug mode.</p> + +<p>If you don't have Ant, you can obtain it from the +<a href="http://ant.apache.org/">Apache Ant home page</a>. Install it and make +sure it is in your executable PATH. Before calling Ant, you need to declare the JAVA_HOME +environment variable to specify the path to where the JDK is installed.</p> + +<p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install +in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of +the space. To fix the problem, you can specify the JAVA_HOME variable like this: +<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> + + +<h3 id="DebugMode">Building in debug mode</h3> + +<p>For immediate application testing and debugging, you can build your application +in debug mode and immediately install it on an emulator. In debug mode, the build tools automatically +sign your application with a debug key. However, you can (and should) also test your +application in release mode. Debug mode simply allows you to run your application without +manually signing the application.</p> + +<p>To build in debug mode:</p> + +<ol> + <li>Open a command-line and navigate to the root of your project directory.</li> + <li>Use Ant to compile your project in debug mode: + <pre>ant debug</pre> + <p>This creates your Android application .apk file inside the project <code>bin/</code> + directory, named <code><em><your_DefaultActivity_name></em>-debug.apk</code>. The file + is already signed with the debug key.</p> + </li> +</ol> + +<p>Each time you change a source file or resource, you must run Ant +again in order to package up the latest version of the application.</p> + +<p>To install and run your application on an emulator, see the following section +about <a href="#Running">Running Your Application</a>.</p> + + +<h3 id="ReleaseMode">Building in release mode</h3> + +<p>When you're ready to release and distribute your application to end-users, you must build +your application in release mode. Once you have built in release mode, it's a good idea to perform +additional testing and debugging with the final .apk.</p> + +<p>To build in release mode:</p> + +<ol> + <li>Open a command-line and navigate to the root of your project directory.</li> + <li>Use Ant to compile your project in release mode: + <pre>ant release</pre> + <p>This creates your Android application .apk file inside the project <code>bin/</code> + directory, named <code><em><your_DefaultActivity_name></em>.apk</code>.</p> + <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point. + You can't install it on an emulator or device until you sign it with your private key.</p> + </li> +</ol> + +<p>Because release mode builds your application unsigned, your next step is to sign +it with your private key, in order to distribute it to end-users. To complete this procedure, +read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> + +<p>Once you have signed your application with a private key, you can install it on an +emulator or device as discussed in the following section about +<a href="#Running">Running Your Application</a>. +You can also try installing it onto a device from a web server. +Simply upload the signed APK to a web site, then load the .apk URL in your Android web browser to +download the application and begin installation. +(On your device, be sure you have enabled <em>Settings > Applications > Unknown sources</em>.)</p> + + +<h2 id="Running">Running Your Application</h2> + +<p>Unless you'll be running your application on device hardware, +you need to launch an emulator upon which you will install your application. +An instance of the Android emulator runs a specific Android platform with specific device configuration +settings. The platform and configuration is defined with an Android Virtual Device (AVD). +So before you can launch your emulator, you must define an AVD.</p> + +<p>If you'll be running your application on device hardware, please read about +<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> instead.</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> + <li><strong>Create an AVD</strong> + <ol> + <li>Open a command-line and navigate to your SDK package's + <code>tools/</code> directory.</li> + <li>First, you need to select a "deployment target." To view available targets, execute: + <pre>android list targets</pre> + <p>This will output a list of available Android targets, such as:</p> +<pre> +id:1 + Name: Android 1.1 + Type: platform + API level: 2 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:2 + Name: Android 1.5 + Type: platform + API level: 3 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +</pre> + <p>Find the target that matches the Android platform upon which you'd like + to run your application. Note the integer value of the <code>id</code> — + you'll use this in the next step.</p> + </li> + <li>Create a new AVD using your selected deployment target: + <pre>android create avd --name <em><your_avd_name></em> --target <em><targetID></em></pre> + <li>Next, you'll be asked whether you'd like to create a custom hardware profile. + If you respond "yes," you'll be presented with a series of prompts to define various aspects of the + device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise, + press return to use all default values ("no" is the default).</li> + </li> + </ol> + </li> + + <li><strong>Launch an emulator</strong></li> + <p>From your SDK's <code>tools/</code> directory, launch an emulator + using an existing AVD (created above): + <pre>emulator -avd <em><your_avd_name></em></pre> + <p>An instance of the emulator will now launch, running the target and configuration + defined by your AVD.</p> + </li> + + <li><strong>Install your application</strong> + <p>From your SDK's <code>tools/</code> directory, install the .apk on the emulator: + <pre>adb install <em>/path/to/your/application</em>.apk</pre> + <p>If there is more than one emulator running, you must specify the emulator upon which to install + the application, by its serial number, with the <code>-s</code> option. For example:</p> + <pre>adb -s emulator-5554 install /my/project/path/myapp.apk</pre> + </li> + <li><strong>Open your application</strong> + <p>In the emulator, open the list of available applications to find + and open your application.</p> + </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>If you don't see your application on the emulator. Try restarting the emulator +(with the same AVD). Sometimes when you install an Activity for the +first time, it won't show up in the application launcher or be accessible by other +applications. This is because the package manager usually examines manifests +completely only on emulator startup.</p> + +<p class="note"><strong>Tip:</strong> If you have only one emulator running, +you can build your application and install it on the emulator in one simple step. +Navigate to the root of your project directory and use Ant to compile the project +with <em>install mode</em>: +<code>ant install</code>. This will build your application, sign it with the debug key, +and install it on the currently running emulator. +If there is more than one emulator currently running +when using the <code>install</code> command, it will fail — it can't select between the +multiple emulators.</p> + +<p>For more information on the tools used above, please see the following documents:</p> +<ul> + <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> + <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> + <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li> +</ul> + + +<h2 id="AttachingADebugger">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> + information:</p> <ol> - <li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server (DDMS) - tool </a>, </strong> which + <li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor + Server (DDMS)</a> tool, </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 + 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> - + <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> Read + about <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port"> + Configuring Your IDE to Attach to the Debugging Port</a>. </li> </ol> diff --git a/docs/html/guide/developing/tools/aidl.jd b/docs/html/guide/developing/tools/aidl.jd index 96e4fec..f370a80 100644 --- a/docs/html/guide/developing/tools/aidl.jd +++ b/docs/html/guide/developing/tools/aidl.jd @@ -1,6 +1,25 @@ page.title=Designing a Remote Interface Using AIDL @jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#implementing">Implementing IPC Using AIDL</a> + <ol> + <li><a href="#aidlsyntax">Create an .aidl File</a></li> + <li><a href="#implementtheinterface">Implementing the Interface</a></li> + <li><a href="#exposingtheinterface">Exposing Your Interface to Clients</a></li> + <li><a href="#parcelable">Pass by value Parameters using Parcelables</a></li> + </ol> + </li> + <li><a href="#calling">Calling an IPC Method</a></li> +</ol> +</div> +</div> + + <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 @@ -10,7 +29,7 @@ the operating system can understand, and "marshall" the object across that bound <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 +<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 @@ -20,12 +39,9 @@ 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> + + +<h2 id="implementing">Implementing IPC Using AIDL</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 @@ -46,7 +62,8 @@ generate code to marshall the parameters.</p> 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> + +<h3 id="aidlsyntax">Create an .aidl File</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 @@ -117,7 +134,7 @@ interface IBankAccountService { int getCustomerList(in String branch, out String[] customerList); }</pre> -<h3>Implementing the Interface <a name="implementtheinterface"></a></h3> +<h3 id="implementtheinterface">Implementing the Interface</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). @@ -152,7 +169,7 @@ private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ <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> +<h3 id="exposingtheinterface">Exposing Your Interface to Clients</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 @@ -165,8 +182,8 @@ private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ exposing_a_service} }</pre> -<a name="parcelable"></a> -<h3>Pass by value Parameters using Parcelables</h3> + +<h3 id="parcelable">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 @@ -181,25 +198,12 @@ current state of the object and writes it to a parcel.</li> 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 +<li>Last but not least, 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> +</ol> + <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 @@ -269,7 +273,7 @@ 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> +<h2 id="calling">Calling an IPC Method</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> diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd new file mode 100644 index 0000000..b8f205e --- /dev/null +++ b/docs/html/guide/developing/tools/avd.jd @@ -0,0 +1,504 @@ +page.title=Android Virtual Devices +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>AVD quickview</h2> + <ul> + <li>You need to create an AVD to run any app in the Android emulator</li> + <li>Each AVD is a completely independent virtual device, with its own + hardware options, system image, and data storage. + <li>You create AVD configurations to model different device environments + in the Android emulator.</li> + </ul> + <h2>In this document</h2> + <ol> + <li><a href="#creating">Creating an AVD</a> + <ol> + <li><a href="#listingtargets">Listing targets</a></li> + <li><a href="#selectingtarget">Selecting a target</a></li> + <li><a href="#createavd">Creating the AVD</a></li> + <li><a href="#hardwareopts">Setting hardware emulation options</a></li> + <li><a href="#location">Default location of the AVD files</a></li> + </ol> + </li> + <li><a href="#managing">Managing AVDs</a> + <ol> + <li><a href="#moving">Moving an AVD</a></li> + <li><a href="#updating">Updating an AVD</a></li> + <li><a href="#deleting">Deleting an AVD</a></li> + </ol> + </li> + <li><a href="#options">Command-line options</a></li> + </ol> + <h2>See Also</h2> + <ol> + <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android + Emulator</a></li> + </ol> +</div> +</div> + +<p>Android Virtual Devices (AVDs) are configurations of emulator options that let +you better model an actual device.</p> + +<p>Each AVD is made up of: </p> + +<ul> +<li>A hardware profile. You can set options to define the hardware +features of the virtual device. For example, you can define whether the device +has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how +much memory it has, and so on. </li> +<li>A mapping to a system image. You can define what version of the +Android platform will run on the virtual device. You can choose a version of the +standard Android platform or the system image packaged with an SDK add-on.</li> +<li>Other options. You can specify the emulator skin you want to use +with the AVD, which lets you control the screen dimensions, appearance, and so +on. You can also specify the emulated SD card to use with the AVD.</li> +<li>A dedicated storage area on your development machine, in which is stored the +device's user data (installed applications, settings, and so on) and emulated SD +card.</li> +</ul> + +<p>You can create as many AVDs as you need, based on the types of devices you +want to model and the Android platforms and external libraries you want to run +your application on. </p> + +<p>In addition to the options in an AVD configuration, you can also +specify emulator command-line options at launch or by using the emulator +console to change behaviors or characteristics at run time. For a complete +reference of emulator options, please see the <a +href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a> +documentation. </p> + +<p>To create and manage AVDs, you use the android tool provided in the Android +SDK. For more information about how to work with AVDs from inside +your development environment, see <a +href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with +ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in +Other IDEs</a>, as appropriate for your environment.</p> + +<h2 id="creating">Creating an AVD</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox-inner"> +<p>The Android SDK does not include any preconfigured AVDs, so +you need to create an AVD before you can run any application in the emulator +(even the Hello World application).</p> +</div> +</div> + +<p>To create an AVD, you use the android tool, a command-line utility +available in the <code><sdk>/tools/</code> directory. Managing AVDs is one +of the two main function of the android tool (the other is creating and updating +Android projects). Open a terminal window and change to the +<code><sdk>/tools/</code> directory, if needed</p> + +<p>To create each AVD, you issue the command <code>android create avd</code>, +with options that specify a name for the new AVD and the system image you want +to run on the emulator when the AVD is invoked. You can specify other options on +the command line also, such as to create an emulated SD card for the new AVD, set +the emulator skin to use, or set a custom location for the AVD's files.</p> + +<p>Here's the command-line usage for creating an AVD: </p> + +<pre>android create avd -n <name> -t <targetID> [-<option> <value>] ... </pre> + +<p>You can use any name you want for the AVD, but since you are likely to be +creating multiple AVDs, you should choose a name that lets you recognize the +general characteristics offered by the AVD. </p> + +<p>As shown in the usage above, you must use the <code>-t</code> (or +<code>--target</code>) argument when creating a new AVD. The argument sets up a +mapping between the AVD and the system image that you want to use whenever the +AVD is invoked. You can specify any Android system image that is available in +your local SDK — it can be the system image of a standard Android platform +version or that of any SDK add-on. Later, when applications use the AVD, they'll +be running on the system that you specify in the <code>-t</code> argument.<p> + +<p>To specify the system image to use, you refer to its <em>target ID</em> +— an integer — as assigned by the android tool. The target ID is not +derived from the system image name, version, or API Level, or other attribute, +so you need to have the android tool list the available system images and the +target ID of each, as described in the next section. You should do this +<em>before</em> you run the <code>android create avd</code> command. +</p> + +<h3 id="listingtargets">Listing targets</h3> + +<p>To generate a list of system image targets, use this command: </p> + +<pre>android list targets</pre> + +<p>The android tool scans the <code><sdk>/platforms</code> and +<code><sdk>/add-ons</code> directories looking for valid system images and +then generates the list of targets. Here's an example of the command output: +</p> + +<pre>Available Android targets: +id:1 + Name: Android 1.1 + Type: platform + API level: 2 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:2 + Name: Android 1.5 + Type: platform + API level: 3 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:3 + Name: Google APIs + Type: add-on + Vendor: Google Inc. + Description: Android + Google APIs + Based on Android 1.5 (API level 3) + Libraries: + * com.google.android.maps (maps.jar) + API for Google Maps + Skins: HVGA (default), HVGA-L, QVGA-P, HVGA-P, QVGA-L</pre> + +<h3 id="selectingtarget">Selecting a target</h3> + +<p>Once you have generated the list of targets available, you can look at the +characteristics of each system image — name, API Level, external +libraries, and so on — and determine which target is appropriate for the +new AVD. </p> + +<p>Keep these points in mind when you are selecting a system image target for +your AVD:</p> +<ul> +<li>The API Level of the target is important, because your application will not +be able to run on a system image whose API Level is less than that required by +your application, as specified in the <code>minSdkVersion</code> attribute of +the application's manifest file. For more information about the relationship +between system API Level and application <code>minSdkVersion</code>, see <a +href="{@docRoot}guide/publishing/versioning.html#minsdkversion">Specifying +Minimum System API Version</a>. +<li>Creating at least one AVD that uses a target whose API Level is greater than +that required by your application is strongly encouraged, because it allows you to +test the forward-compatibility of your application. Forward-compatibility +testing ensures that, when users who have downloaded your application receive a +system update, your application will continue to function normally. </li> +<li>If your application declares a <code>uses-library</code> element in its +manifest file, the application can only run on a system image in which that +external library is present. If you want your application to run on the AVD you +are creating, check the application's <code>uses-library</code> element and +select a system image target that includes that library. + +</ul> + +<h3 id="createavd">Creating the AVD</h3> + +<p>When you've selected the target you want to use and made a note of its ID, +use the <code>android create avd</code> command to create the AVD, supplying the +target ID as the <code>-t</code> argument. Here's an example that creates an +AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5 +system image in the list above): </p> + +<pre>android create avd -n my_android1.5 -t 2</pre> + +<p>If the target you selected was a standard Android system image ("Type: +platform"), the android tool next asks you whether you want to create a custom +hardware profile. </p> + +<pre>Android 1.5 is a basic Android platform. +Do you wish to create a custom hardware profile [no]</pre> + +<p>If you want to set custom hardware emulation options for the AVD, enter +"yes" and set values as needed. If you want to use the default hardware +emulation options for the AVD, just press the return key (the default is "no"). +The android tool creates the AVD with name and system image mapping you +requested, with the options you specified. + +<p class="note">If you are creating an AVD whose target is an SDK add-on, +the android tool does not allow you to set hardware emulation options. It +assumes that the provider of the add-on has set emulation options appropriately +for the device that the add-on is modeling, and so prevents you from resetting +the options. </p> + +<p>For a list of options you can use in the <code>android create avd</code> +command, see the table in <a href="#options">Command-line options for AVDs</a>, +at the bottom of +this page. </p> + +<h3 id="hardwareopts">Setting hardware emulation options</h3> + +<p>When are creating a new AVD that uses a standard Android system image ("Type: +platform"), the android tool lets you set hardware emulation options for virtual +device. The table below lists the options available and the default values, as +well as the names of properties that store the emulated hardware options in the AVD's +configuration file (the config.ini file in the AVD's local directory). </p> + + +<table> +<tr> +<th>Characteristic</th> +<th>Description</th> +<th>Property</th> +</tr> + +<tr> +<td>Device ram size</td> +<td>The amount of physical RAM on the device, in megabytes. Default value is "96". +<td>hw.ramSize</td> +</tr> + +<tr> +<td>Touch-screen support</td> +<td>Whether there is a touch screen or not on the device. Default value is "yes".</td> +<td>hw.touchScreen + + +<tr> +<td>Trackball support </td> +<td>Whether there is a trackball on the device. Default value is "yes".</td> +<td>hw.trackBall</td> +</tr> + +<tr> +<td>Keyboard support</td> +<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td> +<td>hw.keyboard</td> +</tr> + +<tr> +<td>DPad support</td> +<td>Whether the device has DPad keys. Default value is "yes".</td> +<td>hw.dPad</td> +</tr> + +<tr> +<td>GSM modem support</td> +<td>Whether there is a GSM modem in the device. Default value is "yes".</td> +<td>hw.gsmModem</td> +</tr> + +<tr> +<td>Camera support</td> +<td>Whether the device has a camera. Default value is "no".</td> +<td>hw.camera</td> +</tr> + +<tr> +<td>Maximum horizontal camera pixels</td> +<td>Default value is "640".</td> +<td>hw.camera.maxHorizontalPixels</td> +</tr> + +<tr> +<td>Maximum vertical camera pixels</td> +<td>Default value is "480".</td> +<td>hw.camera.maxVerticalPixels</td> +</tr> + +<tr> +<td>GPS support</td> +<td>Whether there is a GPS in the device. Default value is "yes".</td> +<td>hw.gps</td> +</tr> + +<tr> +<td>Battery support</td> +<td>Whether the device can run on a battery. Default value is "yes".</td> +<td>hw.battery</td> +</tr> + +<tr> +<td>Accelerometer</td> +<td>Whether there is an accelerometer in the device. Default value is "yes".</td> +<td>hw.accelerometer</td> +</tr> + +<tr> +<td>Audio recording support</td> +<td>Whether the device can record audio. Default value is "yes".</td> +<td>hw.audioInput</td> +</tr> + +<tr> +<td>Audio playback support</td> +<td>Whether the device can play audio. Default value is "yes".</td> +<td>hw.audioOutput</td> +</tr> + +<tr> +<td>SD Card support</td> +<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td> +<td>hw.sdCard</td> +</tr> + +<tr> +<td>Cache partition support</td> +<td>Whether we use a /cache partition on the device. Default value is "yes".</td> +<td>disk.cachePartition</td> +</tr> + +<tr> +<td>Cache partition size</td> +<td>Default value is "66MB".</td> +<td>disk.cachePartition.size </td> +</tr> +</table> + +<h3 id="location">Default location of the AVD files</h3> + +<p>When you create an AVD, the android tool creates a dedicated directory for it +on your development computer. The directory contains the AVD configuration file, +the user data image and SD card image (if available), and any other files +associated with the device. Note that the directory does not contain a system +image — instead, the AVD configuration file contains a mapping to the +system image, which it loads when the AVD is launched. </p> + +<p>The android tool also creates a <AVD name>.ini file for the AVD at the +root of the .android/avd directory on your computer. The file specifies the +location of the AVD directory and always remains at the root the .android +directory.</p> + +<p>By default, the android tool creates the AVD directory inside +<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and +Settings\<user>\.android\</code> on Windows XP, and +<code>C:\Users\<user>\.android\</code> on Windows Vista. +If you want to use a custom location for the AVD directory, you +can do so by using the <code>-p <path></code> option when +you create the AVD: </p> + +<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre> + +<p>If the .android directory is hosted on a network drive, we recommend using +the <code>-p</code> option to place the AVD directory in another location. +The AVD's .ini file remains in the .android directory on the network +drive, regardless of the location of the AVD directory. </p> + +<h2 id="managing">Managing AVDs</h2> + +<p>The sections below provide more information about how to manage AVDs once you've created them. </p> + +<h3 id="moving">Moving an AVD</h3> + +<p>If you want to move or rename an AVD, you can do so using this command:</p> + +<pre>android move avd -n <name> [-<option> <value>] ...</pre> + +<p>The options for this command are listed in <a href="#options">Command-line +options for AVDs</a> at the bottom of this page. </p> + +<h3 id="updating">Updating an AVD</h3> + +<p>If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the <code>android list targets</code> command will produce this output: + +<pre>The following Android Virtual Devices could not be loaded: +Name: foo +Path: <path>/.android/avd/foo.avd +Error: Invalid value in image.sysdir. Run 'android update avd -n foo' </pre> + +<p>To fix this error, use the <code>android update avd</code> command to recompute the path to the system images.</p> + +<h3 id="deleting">Deleting an AVD</h3> + +<p>You can use the android tool to delete an AVD. Here is the command usage:</p> + +<pre>android delete avd -n <name> </pre> + +<p>When you issue the command, the android tool looks for an AVD matching the +specified name deletes the AVD's directory and files. </p> + + +<h2 id="options">Command-line options for AVDs</h2> + +<p>The table below lists the command-line options you can use with the +android tool. </p> + + +<table> +<tr> + <th width="15%">Action</th> + <th width="20%">Option</th> + <th width="30%">Description</th> + <th>Comments</th> +</tr> + + +<tr> + <td><code>list avds</code></td> + <td> </td> + <td>List all known AVDs, with name, path, target, and skin. </td> + <td> </td> +</tr> +<tr> + <td rowspan="6"><code>create avd</code></td> + <td><code>-n <name> or <br></code></td> + <td>The name for the AVD.</td> + <td>Required</td> +</tr> +<tr> + <td><code>-t <targetID></code></td> + <td>Target ID of the system image to use with the new AVD.</td> + <td>Required. To obtain a list of available targets, use <code>android list + targets</code>.</td> +</tr> +<tr> + <td><code>-c <path></code> or <br> + <code>-c <size>[K|M]</code></td> + <td>The path to the SD card image to use with this AVD or the size of a new SD + card image to create for this AVD.</td> + <td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td> +</tr> +<tr> + <td><code>-f</code></td> + <td>Force creation of the AVD</td> + <td>By default, if the name of the AVD being created matches that of an + existing AVD, the android tool will not create the new AVD or overwrite + the existing AVD. If you specify the <code>-f</code> option, however, the + android tool will automatically overwrite any existing AVD that has the + same name as the new AVD. The files and data of the existing AVD are + deleted. </td> +</tr> + +<tr> + <td><code>-p <path></code></td> + <td>Path to the location at which to create the directory for this AVD's +files.</td> + <td> </td> +</tr> +<tr> + <td><code>-s <name></code> or <br> + <code>-s <width>-<height></code> </td> + <td>The skin to use for this AVD, identified by name or dimensions.</td> + <td>The android tool scans for a matching skin by name or dimension in the +<code>skins/</code> directory of the target referenced in the <code>-t +<targetID></code> argument. Example: <code>-s HVGA-L</code></td> +</tr> +<tr> + <td><code>delete avd</code></td> + <td><code>-n <name></code></td> + <td>Delete the specified AVD.</td> + <td>Required</td> +</tr> +<tr> + <td rowspan="3"><code>move avd</code></td> + <td><code>-n <name></code></td> + <td>The name of the AVD to move.</td> + <td>Required</td> +</tr> +<tr> + <td><code>-p <path></code></td> + <td>The path to the new location for the AVD.</td> + <td> </td> +</tr> +<tr> + <td><code>-r <new-name></code></td> + <td>Rename the AVD.</td> + <td> </td> +</tr> +<tr> + <td><code>update avds</code></td> + <td> </td> + <td>Recompute the paths to all system images.</td> + <td> </td> +</tr> + + + +</table> + diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd index 769491b..82d3c8d 100644 --- a/docs/html/guide/developing/tools/emulator.jd +++ b/docs/html/guide/developing/tools/emulator.jd @@ -14,30 +14,31 @@ 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>To let you model and test your application more easily, the emulator supports +Android Virtual Device (AVD) configurations. AVDs let you specify the Android +platform that you want to run on the emulator, as well as the hardware options +and emulator skin files tht you want to use. Once your application is running on +the emulator, it can use the services of the Android platform to invoke other +applications, access the network, play audio and video, store and retrieve data, +notify the user, and render graphical transitions and themes. </p> <p>The emulator also includes a variety of debug capabilities, such as a console from which you can log kernel output, simulate application interrupts (such as arriving SMS messages or phone calls), and simulate latency effects and dropouts on the data channel.</p> - - - <div class="inline-toc" style="whitespace:nowrap;"> <h4>In this document:</h4> <div class="g-unit g-first" style="whitespace:nowrap;width:35%;"> <ol class="toc"> <li><a href="#overview">Overview</a></li> <li><a href="#starting">Starting and Stopping the Emulator</a></li> +<li><a href="#starting">Android Virtual Devices and the Emulator</a></li> <li><a href="#controlling">Controlling the Emulator</a></li> <li><a href="#startup-options">Emulator Startup Options</a></li> <li><a href="#diskimages">Working with Emulator Disk Images</a> <ol class="toc"> - <li><a href="#systemimages">System Images</a></li> + <li><a href="#defaultimages">Default Images</a></li> <li><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></li> <li><a href="#temporaryimages">Temporary Images</a></li> </ol></li> @@ -76,7 +77,8 @@ on the data channel.</p> <li><a href="#apps">Installing Applications on the Emulator</a></li> <li><a href="#sdcard">SD Card Emulation</a> <ol class="toc"> - <li><a href="#creating">Creating a Disk Image</a></li> + <li><a href="#creatinga">Creating an SD card image using the android tool</li> + <li><a href="#creatingm">Creating an SD card image using mksdcard</a></li> <li><a href="#copying">Copying Files to a Disk Image</a></li> <li><a href="#loading">Loading the Disk Image at Emulator Startup</a></li> </ol></li> @@ -92,12 +94,14 @@ on the data channel.</p> <h2>Overview</h2> <p>The Android emulator is a QEMU-based application that provides a virtual ARM -mobile device on which you can run your Android applications. It provides a full -Android system stack, down to the kernel level, and includes a set of +mobile device on which you can run your Android applications. It runs a full +Android system stack, down to the kernel level, that includes a set of preinstalled applications (such as the dialer) that you can access from your -applications. It provides a skinnable mobile device UI, customizable key -mappings, and a variety of commands and options for controlling the behaviors of -the emulated environment. </p> +applications. You can choose what version of the Android system you want to +run in the emulator by configuring AVDs, and you can also customize the +mobile device skin and key mappings. When launching the emulator and at runtime, +you can use a variety of commands and options to control the its behaviors. +</p> <p>The Android system image distributed in the SDK contains ARM machine code for the Android Linux kernel, the native libraries, the Dalvik VM, and the various @@ -132,9 +136,9 @@ it for developing Android applications.</p> <p>During development and testing of your application, you install and run your application in the Android emulator. You can launch the emulator as a standalone application, from a command line, or you can use it as part of your Eclipse -development environment. In either case, you can specify the startup options -described in this document to control the emulator. - </p> +development environment. In either case, you specify the AVD configuration to +load and any startup options you want to use, as described in this document. +</p> <p>You can run your application on a single instance of the emulator or, depending on your needs, you can start multiple emulator instances and run your @@ -146,9 +150,14 @@ 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> +<code>tools/</code> folder of the SDK. Enter <code>emulator</code> command +like this: </p> + +<pre>emulator -avd <avd_name></pre> + +<p>This initializes the emulator and loads an AVD configuration (see the next +section for more information about AVDs). You will see the emulator window +appear on your screen. </p> <p>If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically, when you run or debug @@ -163,6 +172,27 @@ on the Emulator</a> for information about how to install your application.</p> <a name="controlling"></a> +<a name="avds"></a> + +<h2>Android Virtual Devices and the Emulator</h2> + +<p>To use the emulator, you first must create one or more AVD configurations. In each +configuration, you specify an Android platform to run in the emulator and the set of hardware +options and emulator skin you want to use. Then, when you launch the emulator, you specify +the AVD configuration that you want to load. </p> + +<p>To specify the AVD you want to load when starting the emulator, you use the +<code>-avd</code> argument, as shown in the previous section. </p> + +<p>Each AVD functions as an independent device, with its own private storage for +user data, SD card, and so on. When you launch the emulator with an AVD configuration, +it automatically loads the user data and SD card data from the AVD directory. By default, +the emulator stores the user data, SD card data, and cache in the AVD directory.</p> + +<p>To create and manage AVDs you use the android tool, a command-line utility +included in the SDK. For complete information about how to set up AVDs, see <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</p> + <h2>Controlling the Emulator</h2> <p>You can use emulator <a href="#startup-options">startup options</a> and <a @@ -279,7 +309,7 @@ the keys of your keyboard. </p> when launching the emulator, to control its appearance or behavior. Here's the command-line usage for launching the emulator with options: </p> -<pre>emulator [-<option> [<value>]] ... [-<qemu args>]</pre> +<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> <p>The table below summarizes the available options.</p> @@ -292,7 +322,7 @@ Here's the command-line usage for launching the emulator with options: </p> </tr> <tr> - <td rowspan="8">Help</td> + <td rowspan="9">Help</td> <td><code>-help</code></td> <td>Print a list of all emulator options.</td> <td> </td> @@ -331,9 +361,22 @@ Here's the command-line usage for launching the emulator with options: </p> <td>Print help for defining a custom key mappings file.</td> <td> </td> </tr> - <tr> - <td rowspan="10">Disk Images</td> + <td><code>-help-virtual-device</code></td> + <td>Print help for Android Virtual Device usage.</td> + <td> </td> +</tr> +<tr> + <td>AVD</td> + <td><code>-avd <avd_name></code> or <br> + <code>@<avd_name></code></td> + <td><strong>Required</strong>. Specifies the AVD to load for this emulator + instance.</td> + <td>You must create an AVD configuration before launching the emulator. For + information, see <a href="{@docRoot}guide/developing/tools/avd.html">Android + Virtual Devices</a>.</td> +<tr> + <td rowspan="7">Disk Images</td> <td><code>-cache <filepath></code></td> <td>Use <filepath> as the working cache partition image. </td> <td>Optionally, you can specify a path relative to the current working directory. @@ -345,13 +388,7 @@ Here's the command-line usage for launching the emulator with options: </p> <td>Use <filepath> as the working user-data disk image. </td> <td>Optionally, you can specify a path relative to the current working directory. If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" - in the directory specified in <datadir>. ~/.android/SDK-1.0 (on Linux/Mac) or - C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0 (on Windows). - <p> If you use <code>-data <filepath></code> but the file does not exist, the emulator creates - a file at that location using the specified name. </p> - <p>See <a href="#multipleinstances">Running Multiple Emulator Instances</a> for information about how - to use <code>-data</code> to let multiple emulator instances preserve their user data across sessions.</p> - <p>For more information on disk images, use <code>-help-disk-images</code>.</p> + in the storage area of the AVD being used (see <code>-avd</code>). </td></tr> <!-- <tr> @@ -359,28 +396,32 @@ Here's the command-line usage for launching the emulator with options: </p> <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> <td><code><dir></code> is a path relative to the current working directory. -<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image in the - directory ~/.android/SDK-1.0 (on Linux/Mac) or C:\Documents and Settings\<user>\Local Settings\Application - Data\Android\SDK-1.0 (on Windows). </p><p>For more information on disk images, use <code>-help-disk-images</code>.</p> +<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image +in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information +on disk images, use <code>-help-disk-images</code>.</p> </td></tr> --> +<!-- <tr> <td><code>-image <filepath></code></td> <td>Use <filepath> as the system image.</td> <td>Optionally, you can specify a path relative to the current working directory. Default is <system>/system.img.</td> </tr> +--> <tr> <td><code>-initdata <filepath></code></td> <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> </tr> +<!-- <tr> <td><code>-kernel <filepath></code></td> <td>Use <filepath> as the emulated kernel.</td> <td>Optionally, you can specify a path relative to the current working directory. </td> </tr> +--> <tr> <td><code>-nocache</code></td> <td>Start the emulator without a cache partition.</td> @@ -400,12 +441,14 @@ Here's the command-line usage for launching the emulator with options: </p> <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 @@ -448,8 +491,8 @@ Here's the command-line usage for launching the emulator with options: </p> <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> + <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at + <a href="http://www.nongnu.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> for a list of device types.</p> <p>Here are some examples: </p> @@ -679,7 +722,8 @@ scale in direct relationship with <delay> values.</p> <tr> <td><code>-skin <skinID></code></td> <td>Start the emulator with the specified skin. </td> - <td>The SDK includes a <a href="#skins">choice of four skins</a>:<br /> + <td>The standard Android platforms includes a <a href="#skins">choice of + four skins</a>:<br /> <li>HVGA-L (480x320, landscape)</li> <li>HVGA-P (320x480, portrait) (default) </li> <li>QVGA-L (320x240, landscape)</li> @@ -702,10 +746,16 @@ 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> +files. By default, the Emulator always looks for the disk images in the +private storage area of the AVD in use. If no images exist there when +the Emulator is launched, it creates the images in the AVD directory based on +default versions stored in the SDK. </p> + +<p class="note"><strong>Note:</strong> The default storage location for +AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and +Settings\<user>\.android\</code> on Windows XP, and +<code>C:\Users\<user>\.android\</code> +on Windows Vista.</p> <p>To let you use alternate or custom versions of the image files, the emulator provides startup options that override the default locations and filenames of @@ -713,32 +763,26 @@ the image files. When you use the options, the emulator searches for the image file under the image name or location that you specify; if it can not locate the image, it reverts to using the default names and location.</p> -<p>The emulator uses three types of image files: system image files, runtime +<p>The emulator uses three types of image files: default image files, runtime image files, and temporary image files. The sections below describe how to override the location/name of each type of file. </p> -<a name="systemimages"></a> -<h3>System Images</h3> +<a name="defaultimages"></a> +<h3>Default Images</h3> -<p>System images contain system data and default settings without which the -emulator can not run. The image files are read-only — the emulator reads -the images at startup and does not modify them during the session.</p> - -<p>All of the system image files are stored in a single directory. By default, -the system images are stored in the <code>lib/images</code>' under the -emulator's program location. </p> +<p>When the emulator launches but does not find an existing user data image in +the active AVD's storage area, it creates a new one from a default version +included in the SDK. The default user data image is read-only. The image +files are read-only.</p> <p>The emulator provides the <code>-system <dir></code> startup option to -let you override the location under which the emulator looks for the system -images files. </p> +let you override the location under which the emulator looks for the default +user data image. </p> -<p>The emulator also provides startup options that let you override the names of -the system images, as described in the table below. When you use one of the -options, the emulator looks in the default directory, or in a custom location -(if you specified <code>-system <dir></code>). Note that, if you provide -alternate system image file, it must contain the same type of data as the -default. For example, your override of the system.img file must point to a disk -image containing an Android system. </p> +<p>The emulator also provides a startup option that lets you override the name +of the default user data image, as described in the table below. When you use the +option, the emulator looks in the default directory, or in a custom location +(if you specified <code>-system <dir></code>). </p> <table> @@ -748,6 +792,7 @@ image containing an Android system. </p> <th width="40%" >Comments</th> </tr> +<!-- <tr> <td><code>kernel-qemu.img</code></td> <td>The emulator-specific Linux kernel image</td> @@ -765,7 +810,7 @@ image containing an Android system. </p> <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> @@ -784,13 +829,7 @@ 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> +described above. The emulator stores the new image with the files of the active AVD.</p> <!-- <p>The emulator provides a startup option, <code>-datadir <dir></code>, @@ -801,7 +840,7 @@ 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> +in the AVD directory, or in a custom location (if you specified a path with the filename). </p> <table> <tr> @@ -837,12 +876,12 @@ 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 +in the AVD directory as described above, and at the custom location/name that you specified at startup. </p> <ul> -<li>If it finds a user-data image, it mounts the image and makes it available to the system -for reading/writing of user data. </li> +<li>If it finds a user-data image, it mounts the image and makes it available +to the system for reading/writing of user data. </li> <li>If it does not find one, it creates an image by copying the system user-data image (userdata.img), described above. At device power-off, the system persists the user data to the image, so that it will be available in the next session. @@ -850,13 +889,9 @@ 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> +<p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator, +each emulator instance now gets its own dedicated storage. There is no need +to use the <code>-d</code> option to specify an instance-specific storage area.</p> <h4>SD Card</h4> @@ -864,6 +899,10 @@ create), by using the <code>-data <name></code> option with a unique to simulate removeable storage in an actual device. For information about how to create an emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> +<p>You can also use the android tool to automatically create an SD Card image +for you, when creating an AVD. For more information, see <a +href="{@docRoot}guide/developing/tools/avd.html#options">Command-line options for AVDs</a>. + <a name="temporaryimages"></a> <h3>Temporary Images</h3> @@ -1637,21 +1676,11 @@ kilobits/sec):</p> <h2>Running Multiple Emulator Instances</h2> -<p>You can run multiple instances of the emulator concurrently, if necessary. Each emulator instance can use a separate user-data image file and a different console port. This lets you manage each instance in isolation. </p> - -<p>However, if you will run multiple emulator instances, note that there are limitations on the capability of each instance to maintain its persistent user data — user settings and installed applications — across sessions. Specifically:</p> - -<ul> - <li>By default, only the first-launched emulator instance can preserve user data across sessions. When a session closes, - the emulator stores the user data to a user-data image file — by default, it stores the data in the file - <code>~/.android/SDK-1.0/userdata-qemu.img </code>(on Linux and Mac) or <code>C:\Documents and Settings\<user>\Local - Settings\Application Data\Android\SDK-1.0\userdata-qemu.img</code> (on Windows) in your development computer.</li> - -<li>Emulator instances that you start after the first instance (that are running concurrently) can also store user data during a session, but they <em>do not</em> preserve it for the next session, unless you have specified a unique user-data image file in which the data should be stored. </li> - -</ul> - -<p>To run multiple emulator instances and let each maintain user data across sessions, start the instances with the <code>-data</code> option (see <a href="#startup-options">Startup Options</a>) and supply the path to a user-data file. </p> +<p>Through the AVDs configurations used by the emulator, you can run multiple +instances of the emulator concurrently, each with its own AVD configuration and +storage area for user data, SD card, and so on. You no longer need to use the +<code>-d</code> option when launching the emulator, to point to an +instance-specific storage area. </p> <a name="apps"></a> @@ -1675,19 +1704,43 @@ For more information about the user-data partition and other emulator storage, see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> <a name="sdcard"></a> +<a name="creating"></a> <h2>SD Card Emulation</h2> -<p>You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card in the device. The sections below describe how to create the disk image, how to copy files to it, and how to load it in the emulator at startup. </p> -<p>Note that you can only load disk image at emulator startup. Similarly, you can not remove a simulated SD card from a running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with adb or the emulator. </p> +<p>You can create a disk image and then load it to the emulator at startup, to +simulate the presence of a user's SD card in the device. To do this, you can use +the android tool to create a new SD card image with a new AVD, or you can use +the mksdcard utility included in the SDK. </p> -<p>The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.</p> +<p>The sections below describe how to create an SD card disk image, how to copy +files to it, and how to load it in the emulator at startup. </p> -<a name="creating"></a> +<p>Note that you can only load disk image at emulator startup. Similarly, you +can not remove a simulated SD card from a running emulator. However, you can +browse, send files to, and copy/remove files from a simulated SD card either +with adb or the emulator. </p> + +<p>The emulator supports emulated SDHC cards, so you can create an SD card image +of any size up to 128 gigabytes.</p> + +<h3 id="creatinga">Creating an SD card image using the android tool</h3> -<h3>Creating a Disk Image</h3> +<p>The easiest way to create a new SD card is to use the android tool. When +creating an AVD, you simply specify the <code>-c</code> option, like this: </p> -<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk image that you can load in the emulator at startup. You can access mksdcard in the tools/ directory of the SDK and create a disk image like this: </p> +<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> + +<p>You can also use the <code>-c</code> option to specify a path to an SD card +image to use in the new AVD. For more information, see <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. +</p> + +<h3 id="creatingm">Creating an SD card image using mksdcard</h3> + +<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk +image that you can load in the emulator at startup. You can access mksdcard in +the tools/ directory of the SDK and create a disk image like this: </p> <pre>mksdcard <size> <file></pre> @@ -1700,13 +1753,23 @@ see <a href="#diskimages">Working with Emulator Disk Images</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> +<p>Once you have created the disk image, you can copy files to it prior to +loading it in the emulator. To copy files, you can mount the image as a loop +device and then copy the files to it, or you can use a utility such as mtools to +copy the files directly to the image. The mtools package is available for Linux, +Mac, and Windows.</p> <a name="loading"></a> <a name="step3" id="step3"></a> <h3>Loading the Disk Image at Emulator Startup</h3> -<p>To load FAT32 disk image in the emulator, start the emulator with the <code>-sdcard</code> flag and specify the name and path of your image (relative to the current working directory): </p> + +<p>By default, the emulator loads the SD card image that is stored with the active +AVD (see the <code>-avd</code> startup option).</p> + +<p>Alternatively, you ca start the emulator with the +<code>-sdcard</code> flag and specify the name and path of your image (relative +to the current working directory): </p> <pre>emulator -sdcard <filepath></pre> diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index b491a4f..2c9e45d 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -8,23 +8,29 @@ applications on the Android platform. The most important of these are the Androi 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> + <dl> <dt><a href="adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt> <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment, making creating and debugging your Android applications easier and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications.</dd> + <dt><a href="emulator.html">Android Emulator</a></dt> + <dd>A QEMU-based device-emulation tool that you can use to design, + debug, and test your applications in an actual Android run-time environment. </dd> - <dt><a href="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="avd.html">Android Virtual Devices (AVDs)</a></dt> + <dd>Virtual device configurations that you create, to model device + characteristics in the Android Emulator. In each configuration, you can + specify the Android platform to run, the hardware options, and the + emulator skin to use. Each AVD functions as an independent device with + it's own storage for user data, SD card, and so on. </dd> + + <dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt> + <dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface. + It provides a visual representation of your layout's hierarchy of Views and a magnified inspector + of the current display with a pixel grid, so you can get your layout just right. + </dd> <dt><a href="draw9patch.html">Draw 9-patch</a></dt> <dd>The Draw 9-patch tool allows you to easily create a @@ -79,10 +85,9 @@ applications on the emulator. </p> 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 + <dt><a href="othertools.html#android">android</a></dt> + <dd>A script that lets you manage AVDs and generate <a href="http://ant.apache.org/" title="Ant">Ant</a> build files that - you can use to compile your Android applications. If you are developing - on Eclipse with the ADT plugin, you won't need to use this script. </dd> + you can use to compile your Android applications. </dd> </dl> diff --git a/docs/html/guide/developing/tools/othertools.jd b/docs/html/guide/developing/tools/othertools.jd index eaa0b76..603609e 100644 --- a/docs/html/guide/developing/tools/othertools.jd +++ b/docs/html/guide/developing/tools/othertools.jd @@ -3,16 +3,32 @@ page.title=Other Tools <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> +<p>All of the tools are included in the Android SDK and are accessible from the <code><sdk>/tools/</code> directory.</p> <h2>Contents</h2> <dl> + <dt><a href="#android">android</a></dd> <dt><a href="#mksdcard">mksdcard</a></dt> <dt><a href="#dx">dx</a></dt> - <dt><a href="#activitycreator">activitycreator</a></dd> </dl> +<a name="activitycreator"></a> +<h2 id="android">android</h2> + +<p>The android tool is a script that lets you create and manage Android Virtual Devices (AVDs) and, if you are developing using Ant, generate template Android projects to help you get started quickly. </p> + +<p>For information about how to use the android tool to manage AVDs, see <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. </p> + +<p>For information about how to use the android tool to create or update a project, see <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>. </p> + +<p>Note that if you are developing in Eclipse with the ADT plugin, you will use the android tool to manage the AVDs you create, but you will not use the android tool for creating a project. The ADT plugin provides a New Project Wizard that helps you set up an Android project in Eclipse. </p> + +<p>If you are developing in Ant, you will use the android tool to manage your AVDs, and you can also use it to create or update a project. </p> + +<p class="note">Note: The android tool replaces the activitycreator tool provided in previous SDK releases.</p> + + <a name="mksdcard"></a> <h2>mksdcard</h2> @@ -21,7 +37,7 @@ page.title=Other Tools <pre>mksdcard [-l label] <size>[K|M] <file></pre> -</p>The table below lists the available options/arguments</p> +<p>The table below lists the available options/arguments</p> <table> <tr> @@ -57,48 +73,6 @@ You can also specify size in kilobytes or megabytes, by appending a "K" or "M" t <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 index dd3f4bb..95ae823 100644 --- a/docs/html/guide/developing/tools/traceview.jd +++ b/docs/html/guide/developing/tools/traceview.jd @@ -1,23 +1,32 @@ 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> +<div id="qv-wrapper"> +<div id="qv"> -<h2>Contents</h2> + <h2>In this document</h2> +<ol> + <li><a href="#creatingtracefiles">Creating Trace Files</a></li> + <li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li> + <li><a href="#runningtraceview">Viewing Trace Files in Traceview</a> + <ol> + <li><a href="#timelinepanel">Timeline Panel</a></li> + <li><a href="#profilepanel">Profile Panel</a></li> + </ol></li> + <li><a href="#format">Traceview File Format</a> + <ol> + <li><a href="#datafileformat">Data File Format</a></li> + <li><a href="#keyfileformat">Key File Format</a></li> + </ol></li> + <li><a href="#knownissues">Traceview Known Issues</a></li> + <li><a href="#dmtracedump">Using dmtracedump</a></li> +</ol> +</div> +</div> -<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> +<p>Traceview is a graphical viewer for execution logs +saved by your application. Traceview can help you debug your application and +profile its performance. The sections below describe how to use the program. </p> <a name="creatingtracefiles"></a> @@ -63,10 +72,10 @@ 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> +can create an SD card image named "imgcd" and mount it when launching the emulator like so:</p> <pre> -<b>$</b> mksdcard 1024M ./imgcd -<b>$</b> emulator -sdcard ./img +<b>$</b> mksdcard 1024M ./imgcd +<b>$</b> emulator -sdcard ./imgcd </pre> <p>For more information, read about the <a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">mksdcard tool</a>.</p> |