diff options
Diffstat (limited to 'docs/html/guide/developing/develop-and-debug.jd')
| -rw-r--r-- | docs/html/guide/developing/develop-and-debug.jd | 675 |
1 files changed, 675 insertions, 0 deletions
diff --git a/docs/html/guide/developing/develop-and-debug.jd b/docs/html/guide/developing/develop-and-debug.jd new file mode 100644 index 000000000000..6a337a9a4433 --- /dev/null +++ b/docs/html/guide/developing/develop-and-debug.jd @@ -0,0 +1,675 @@ +page.title=Develop and Debug +@jd:body + +<p>This page offers an introduction to developing and debugging +applications on Android. It teaches how to +create, build, run and debug your Android code. Alternatively, you may like +to begin with the +<a href="/android/intro/hello-android.html">Hello Android tutorial</a>. </p> + +<h2>Contents</h2> + +<ol class="toc"> +<li><a href="#developingwitheclipse">Developing Android Applications on Eclipse</a></li> +<li><a href="#otherides">Developing Android Applications with Other IDEs and Tools</a></li> +<li><a href="#signing">Signing Your Applications</a></li> +<li><a href="#apidemos">Using the ApiDemos Sample Applications</a></li> +<li><a href="#debugging">Debugging</a></li> +<li><a href="#additionaldebugging">Debug and Test Settings on the Device</a></li> +<li><a href="#toptips">Top Debugging Tips</a></li> +<li><a href="#building">Building and Installing an Android Application</a></li> +<li><a href="#uninstalling">Removing an Android Application</a></li> +<li><a href="#tips">Eclipse Tips</a></li> +</ol> + + + +<a name="developingwitheclipse"></a> + +<h2 style="clear: right;"> +Developing Android Applications on Eclipse</h2> + +<p>To begin developing Android applications in the Eclipse IDE, you first create an Android +project and then set up a launch configuration. After that, you can write, run, and debug +your application. </p> + +<p>The sections below provide instructions assuming that you have installed the ADT plugin +in your Eclipse environment. If you haven't installed the ADT plugin, you should do that +before using the instructions below. See the <a href="{@docRoot}intro/installing.html#installingplugin">Installing the +Eclipse Plugin (ADT)</a> for more information. + +<a name="creatingaproject" id="creatingaproject"></a> + +<h3>Creating an Android Project</h3> + +<p>The ADT plugin provides a New Project Wizard that you can use to quickly create an +Eclipse project for new or existing code. To create the project, follow these steps:</p> + +<a name="existingcode"></a> + +<ol> + <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong></li> + <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and press <strong>Next</strong></li> + <li>Select the contents for the project: + <ul> + <li>Select <strong>Create new project in workspace</strong> to start a project for new code. + <p>Enter the project name, the base package name, the name of a single Activity class to create as a stub .java file, and a name to use for your application.</p></li> + <li>Select <strong>Create project from existing source</strong> to start a project from existing code. Use this option if you want to build and run any of the sample applications included with the SDK. The sample applications are located in the samples/ directory in the SDK. + <p>Browse to the directory containing the existing source code and click OK. If the directory contains a valid Android manifest file, the ADT plugin fills in the package, activity, and application names for you.</p> + </li> + </ul> + </li> + <li>Press <strong>Finish</strong>.</li> +</ol> + +<p>The ADT plugin creates the these folders and + files for you as appropriate for the type of project:</p> + + <ul> + <li>src/ A + folder that includes your stub .java Activity file.</li> + <li>res/ A folder for your + resources.</li> + <li>AndroidManifest.xml The + manifest for your project. </li> + </ul> + +</ol> + +<a name="launchconfig" id="launchconfig"></a> + +<h3>Creating a Launch Configuration </h3> + +<p>Before you can run and debug your application in Eclipse, you must create a launch configuration for it. A launch configuration specifies the project to launch, the Activity to start, the emulator options to use, and so on. </p> + +<p>To create a launch configuration for the application, follow these steps as appropriate for your Eclipse version:</p> + +<ol> + + <li>Open the launch configuration manager. + <ul> + <li>In Eclipse 3.3 (Europa), select <strong>Run </strong>> + <strong>Open Run Dialog... </strong>or <strong>Run </strong>> + <strong>Open Debug Dialog... </strong>as appropriate. + </li> + <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> + <strong>Run Configurations... </strong>or <strong>Run </strong>> + <strong>Debug Configurations... </strong>as appropriate. + </li> + </ul> + </li> + <li>In the project type list on the left, locate the <strong> Android Application</strong> item and double-click it (or right-click > <strong>New</strong>), to create a new launch configuration.</li> + <li>Enter a name for your configuration.</li> + <li>On the Android tab, browse for the project and Activity to start.</li> + <li>On the Target tab, set the desired screen and network properties, as well as any other <a href="{@docRoot}reference/emulator.html#startup-options">emulator startup options</a>.</li> + <li>You can set additional options on the Common tab as desired.</li> + <li>Press <strong>Apply</strong> to save the launch configuration, or press <strong>Run</strong> or <strong>Debug</strong> (as appropriate).</li> + +</ol> + +<a name="installingrunningdebugging" id="installingrunningdebugging"></a> + +<h3>Running and Debugging an Application</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> + +From the Eclipse main menu, select <strong>Run</strong> > <strong>Run</strong> or <strong>Run</strong> > <strong>Debug</strong> as appropriate, to run or debug the active launch configuration. </li> + +<p>Note that the active launch configuration is the one most recently selected in the Run configuration manager. It does not necessarily correspond to the application that is selected in the Eclipse Navigation pane (if any).</p> + +<p>To set or change the active launch configuration, use the launch configuration manager. See <a href="#launchconfig">Creating a Launch Configuration</a> for information about how to access the launch configuration manager.</strong>.</p> + +<p>Running or debugging the application triggers these actions:</p> +<ul><li>Starts the emulator, if it is not already running. </li> + <li>Compiles the project, if there have been changes since the last build, and installs the application on the emulator. </li> + <li><strong>Run</strong> starts the application. </li> + <li><strong>Debug</strong> starts the application in "Wait for debugger" mode, then opens the Debug perspective and attaches the Eclipse Java debugger to the application.</li> + + </ul> + +<a name="otherides" id="otherides"></a> +<h2>Developing Android Applications with Other IDEs and Tools</h2> +<p>The recommended way to develop an Android application is to use + <a href="#developingwitheclipse">Eclipse + with the ADT plugin</a>. This plugin provides editing, building, + and debugging functionality integrated right into the IDE. </p> + +<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, + or use Eclipse without the ADT plugin, you can do that instead. The SDK + provides the tools you need to set up, build, and debug your application. + </p> + + +<h3>Creating an Android Project </h3> + +<p>The Android SDK includes <code>activityCreator</code>, a program that generates a number of stub files for your project, as well as a build file. You can use the program to create an Android project for new code or from existing code, such as the sample applications included in the SDK. For Linux and Mac, the SDK provides <code>activitycreator</code> and for Windows, <code>activityCreator.bat</code>, a batch script. Regardless of platform, you can use <code>activitycreator</code> in the same way. </p> + +<p>To run <code>activityCreator</code> and create an Android project, follow these steps:</p> + +<ol> + <li> In the command line, change to the <code>tools/</code> directory of the SDK and create a new directory for your project files. If you are creating a project from existing code, change to the root folder of your application instead. </li> + + <li><p>Run <code>activityCreator</code>. In the command, you must specify a fully-qualified class name as an argument. If you are creating a project for new code, the class represents the name of a stub class that the script will create. If you are creating a project from existing code, you must specify the name of one Activity class in the package. Command options for the script include: +<ul> + <li><code>--out <folder></code> which sets the output directory. By default, the output directory is the current directory. If you created a new directory for your project files, use this option to point to it. </li> + <li><code>--ide intellij</code>, which generates IntelliJ IDEA project files in the newly created project</li> +</ul> +</li> +</ol> + +<p>Here's an example:</p> +<pre> +~/android_linux_sdk/tools $ ./activityCreator.py --out myproject your.package.name.ActivityName +package: your.package.name +out_dir: myproject +activity_name: ActivityName +~/android_linux_sdk/tools $ </pre> + +<p>The <code>activityCreator</code> script generates the following files and directories (but will not overwrite existing ones):</p> + +<ul> + <li><code>AndroidManifest.xml</code> The application manifest file, synced to the specified Activity class for the project.</li> + <li><code>build.xml</code> An <code>Ant</code> file that you can use to build/package the application.</li> + <li><code>src<em>/your/package/name/ActivityName</em>.java</code> The Activity class you specified on input.</li> + <li><code><em>your_activity</em>.iml, <em>your_activity</em>.ipr, + <em>your_activity</em>.iws </code> [<em>only + with the <code>-ide intelliJ</code> flag</em>] intelliJ project + files. </li> + <li><code>res/</code> A directory to hold resources. </li> + <li><code>src/</code> The source directory. + <li><code>bin/</code> The output directory for the build script.</li> +</ul> + +<p>You can now move your folder wherever you want for development, but keep in mind + that you'll have to use the <a href="{@docRoot}reference/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="buildingwithant"></a> + +<h3>Building an Android Application</h3> +<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> + +<h3>Running an Android Application</h3> +<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}reference/adb.html">adb</a> tool as described here:</p> +<ol> + <li>Start the emulator (run <code><em><your_sdk_dir></em>/tools/emulator</code> from the command line)</li> + <li>On the emulator, navigate to the home screen (it is best not to have that + application running when you reinstall it on the emulator; press the <strong>Home</strong> key + to navigate away from that application).</li> + <li>Run <code>adb install <em>myproject</em>/bin/<<em>appname</em>>.apk</code> to upload + the executable. So, for example, to install the Lunar Lander sample, navigate + in the command line to <code><em><your_sdk_dir></em>/sample/LunarLander</code> and type <code>../../tools/adb install bin/LunarLander.apk</code></li> + <li>In the emulator, open the list of available applications, and scroll down to + select and start your application. </li> +</ol> +<p class="note"><strong>Note:</strong> When you install an Activity for the + first time, you might have to restart the emulator before it shows up in the + application launcher, or other applications can call it. This is because + the package manager usually only examines manifests completely on emulator + startup.</p> + +<h3>Attaching a Debugger to Your Application</h3> +<p>This section describes how to display debug information on the screen (such + as CPU usage), as well as how to hook up your IDE to debug running applications + on the emulator. </p> + +<p>Attaching a debugger is automated using the Eclipse plugin, + but you can configure other IDEs to listen on a debugging port to receive debugging + information.</p> +<ol> + <li><strong>Start the <a href="{@docRoot}reference/ddms.html">Dalvik Debug Monitor Server (DDMS) + tool </a>, </strong> which + acts as a port forwarding service between your IDE and the emulator.</li> + <li><strong>Set + optional debugging configurations on + your emulator</strong>, such as blocking application startup for an activity + until a debugger is attached. Note that many of these debugging options + can be used without DDMS, such as displaying CPU usage or screen refresh + rate on the emulator.</li> + <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> We + include information on <a href="#eclipse">how to set up Eclipse to debug + your project</a>. </li> + +<a name="eclipse" id="eclipse"></a> + +</ol> +<h3>Configuring your IDE to attach to the debugging port</h3> + +<p>DDMS will assign a specific debugging port to every virtual machine that it + finds on the emulator. You must either attach your IDE to that + port (listed on the Info tab for that VM), or you can use a default port 8700 + to connect to whatever application is currently selected on the list of discovered + virtual machines.</p> +<p>Your IDE should attach to your application running on the emulator, showing you + its threads and allowing you to suspend them, inspect their state, and set breakpoints. + If you selected "Wait for debugger" in the Development settings panel + the application will run when Eclipse connects, so you will need to set any breakpoints + you want before connecting.</p> +<p>Changing either the application being debugged or the "Wait for debugger" + option causes the system to kill the selected application if it is currently + running. You can use this to kill your application if it is in a bad state + by simply going to the settings and toggling the checkbox.</p> + +<a name="signing" id="signing"></a> + +<h2>Signing Your Applications</h2> + +<p>The Android system requires that all installed applications are digitally signed — +the 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 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>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 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 release mode, the tools compile your .apk without signiing it. You must then use Keytool +to generate your own keystore/key and then use the Jarsigner tool, also included in the JDK, +to sign the .apk.</li> +</ul> + +<h3>Basic Setup for Signing</h3> + +<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> + +<h3>Signing in Eclipse/ADT</h3> + +<p>If you are developing in Eclipse and have set up Keytool as described above, signing +in debug mode is enabled by default. When you run or debug your app, 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>To compile your application in release mode, right-click the project in the Package +pane and select Android Tools > Export Application Package. Alternatively, you can follow the +"Exporting the unsigned .apk" link in the Manifest Editor overview page. After you have saved +the exported .apk, you need to use Jarsigner to sign the .apk with your own key before +distribution. If you don't have a key, you can use Keystore to create a keystore and key with +all the appropriate fields. If you already have a key, such as a corporate key, you can use +that to sign the .apk.</p> + +<h3>Signing in Ant</h3> + +<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>To compile your application in release mode, all you need to do is specify a 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. After you have compiled +the.apk, you need to use Jarsigner to sign the .apk with your own key before +distribution. If you don't have a key, you can use Keystore to create a keystore and key +with all the appropriate fields. If you already have a key, such as a corporate key, you +can use that to sign the .apk.</p> + +<h3>Expiry of the Debug Certificate</h3> + +<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 1 year 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> + +<h2 id="apidemos">Using the ApiDemos Sample Applications</h2> + +<p>The Android SDK includes a set of sample applications that demonstrate much of +the functionality and API usage needed for your applications. The ApiDemos package is +preinstalled on the emulator, so you can access it by starting an emulator and sliding +open the home screen's application drawer. </p> + +<p>You can find the source code corresponding to the ApiDemos apps in <code><SDK> +/samples/ApiDemos</code> and look at it to learn more about how it is implemented.</p> + +<p>If you want, you can load the ApiDemos sample applications as source projects and modify +them, then run them in the emulator. However, to do so, you need to uninstall the preinstalled +version of ApiDemos first. If you try to run or modify ApiDemos from your development environment +without removing the preinstalled version first, you will get an install error.</p> + +<p>For information about how to uninstall and then reinstall ApiDemos so that you can work with +them in your development environment, see the troubleshooting topic +<a href="{@docRoot}kb/troubleshooting.html#apidemosreinstall">I can't install ApiDemos +apps in my IDE because of a signing error</a>.</p> + +<a name="debugging" id="debugging"></a> + +<h2>Debugging</h2> + +<p>Android has a fairly extensive set of tools to help you debug your programs: </p> +<ul> + <li><a href="{@docRoot}reference/ddms.html"><strong>DDMS</strong></a> - A graphical program that + supports port forwarding (so you can set up breakpoints in your code in your + IDE), screen captures on the emulator, thread and stack information, + and many other features. You can also run logcat to retrieve your Log messages. + See the linked topic for more information. </li> + <li><strong><a href="{@docRoot}reference/ddms.html#logcat">logcat</a></strong> - Dumps a log of system + messages. The messages include a stack trace when the emulator throws an error, + as well as Log messages. To run logcat, see the linked topic. + + <pre>... +I/MemoryDealer( 763): MemoryDealer (this=0x54bda0): Creating 2621440 bytes heap at 0x438db000 +<span style="background-color:#CCCCCC; border-bottom:medium">I/Logger( 1858): getView() requesting item number 0 +I/Logger( 1858): getView() requesting item number 1 +I/Logger( 1858): getView() requesting item number 2</span> +D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllApps} +...</pre> + + </li> + <li><p><strong>{@link android.util.Log Android Log}</strong>- A logging + class to print out messages to a log file on the emulator. You can read messages + in real time if you run logcat on DDMS (covered next). Add a few logging + method calls to your code.</p> + <p>To use the <code>Log</code> class, you just call <code>Log.v()</code> + (verbose), <code>Log.d()</code> (debug), <code>Log.i()</code> (information), + <code>Log.w()</code> (warning) or <code>Log.e</code> (error) depending + on the importance you wish to assign the log message.</p> + <code>Log.i("MyActivity", "MyClass.getView() + — Requesting item number " + position)</code> + <p>You can use logcat to read these messages</p></li> + <li><strong><a href="{@docRoot}reference/traceview.html">Traceview</a> </strong>- Android can save + a log of method calls and times to a logging file that you can view in a + graphical reader called Traceview. See the linked topic for more information. </li> +</ul> +<ul> + <li><a href="#developingwitheclipse"><strong>Eclipse plugin</strong></a> - The Eclipse + Android plugin incorporates a number of these tools (ADB, DDMS, logcat output, + and other functionality). See the linked topic for more information. </li> + <li><strong>Debug and Test Device Settings</strong> - Android exposes several settings + that expose useful information such as CPU usage and frame rate. See <a href="#additionaldebugging">Debug + and Test Settings on the Emulator</a> below. </li> +</ul> +<p>Also, see the <a href="{@docRoot}kb/troubleshooting.html">Troubleshooting</a> section + of the doc to figure out why your application isn't appearing on the emulator, + or why it's not starting. </p> + +<a name="additionaldebugging" id="additionaldebugging"></a> + +<h2>Debug and Test Settings on the Device</h2> + +<p>Android lets you set a number of settings that will make it easier to test + and debug your applications. To get to the development settings page on the emulator, + go to <strong>Dev Tools </strong>> <strong>Development Settings</strong>. + This will open the development settings page with the following options (among + others):</p> +<ul> + <li><strong>Debug app</strong> Selects the application that + will be debugged. You do not need to set this to attach a debugger, but setting + this value has two effects: + <ul> + <li>It will prevent Android from throwing an error if you pause on + a breakpoint for a long time while debugging.</li> + <li>It will enable you to select the <em>Wait for Debugger</em> option + to pause application startup until your debugger attaches (described + next). </li> + </ul> + </li> + <li><strong>Wait for debugger </strong> + Blocks the selected application from loading until a debugger attaches. This + way you can set a breakpoint in onCreate(), which is important to debug + the startup process of an Activity. When you change this option, any + currently running instances of the selected application will be killed. + In order to check this box, you must have selected a debug application + as described in the previous option. You can do the same thing by adding + {@link android.os.Debug#waitForDebugger()} to your code. </li> + <li><strong>Immediately destroy activities</strong> Tells the + system to destroy an activity as soon as it is stopped (as if Android had to + reclaim memory). This is very useful for testing the {@link android.app.Activity#onSaveInstanceState} + / {@link android.app.Activity#onCreate(android.os.Bundle)} code path, which would + otherwise be difficult to force. Choosing this option will probably reveal + a number of problems in your application due to not saving state.</li> + <li><strong>Show screen updates</strong> + Flashes a momentary pink rectangle on any screen sections that are being + redrawn. This is very useful for discovering unnecessary screen drawing. </li> + <li><strong>Show CPU usage</strong> Displays CPU meters at the + top of the screen, showing how much the CPU is being used. The top red bar + shows overall CPU usage, and the green bar underneath it shows the CPU time + spent in compositing the screen. <em>Note: You cannot turn this feature off + once it is on, without restarting the emulator.</em> </li> + <li><strong>Show background</strong> Displays a background pattern + when no activity screens are visible. This typically does not happen, but + can happen during debugging. </li> +</ul> +<p>These settings will be remembered across emulator restarts. </p> + +<a name="toptips" id="toptips"></a> + +<h2>Top Debugging Tips</h2> +<!-- +<ul> + <li><a href="#stackdump">Quick stack dump</a></li> + <li><a href="#displayinfo">Displaying useful info on the emulator screen </a></li> + <li><a href="#dumpstate">Getting system state information from the emulator (dumpstate)</a></li> + <li><a href="#dumpsys">Getting application state information from the emulator (dumpsys)</a></li> + <li><a href="#radioinfo">Getting wireless connectivity information</a></li> + <li><a href="#loggingdata">Logging Trace Data</a></li> + <li><a href="#logradio">Logging Radio Data </a></li> + <li><a href="#adb">Running adb</a></li> + <li><a href="#screencaps">Getting screen captures from the emulator</a></li> + <li><a href="#debughelpers">Using debug helper classes</a></li> +</ul> +--> +<dl> +<dt>Quick stack dump <a name="stackdump" id="stackdump"></a></dt> +<dd>To obtain a stack dump from emulator, you can log +in with <code>adb shell</code>, use "ps" to find the process you +want, and then "kill -3 ". The stack trace appears in the log file. +</dd> + +<dt>Displaying useful info on the emulator screen<a name="displayinfo" id="displayinfo"></a></dt> +<dd>The device can display useful information such as CPU usage or highlights +around redrawn areas. Turn these features on and off in the developer settings +window as described in <a href="#additionaldebugging">Setting debug and test +configurations on the emulator</a>. +</dd> + +<dt>Getting system state information from the emulator (dumpstate)<a name="dumpstate" id="dumpstate"></a> </dt> +<dd>You can access dumpstate information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}reference/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting application state information from the emulator (dumpsys)<a name="dumpsys" id="dumpsys"></a></dt> +<dd>You can access dumpsys information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}reference/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting wireless connectivity information <a name="radioinfo" id="radioinfo"></a></dt> +<dd>You can get information about wireless connectivity using the Dalvik Debug +Monitor Service tool. From the <strong>Device</strong> menu, select "Dump +radio state".</dd> + +<dt>Logging Trace Data<a name="loggingdata" id="loggingdata"></a></dt> +<dd>You can log method calls and other tracing data in an activity by calling +android.os.Debug.startMethodTracing(). See <a +href="{@docRoot}reference/traceview.html">Running the Traceview Debugging +Program</a> for details. </dd> + +<dt>Logging Radio Data<a name="logradio" id="logradio"></a></dt> +<dd>By default, radio information is not logged to the system (it is a lot of +data). However, you can enable radio logging using the following commands: + +<pre> +adb shell +logcat -b radio +</pre> +</dd> + +<dt>Running adb<a name="adb" id="adb"></a></dt> +<dd>Android ships with a tool called adb that provides various capabilities, including +moving and syncing files to the emulator, forwarding ports, and running a UNIX +shell on the emulator. See <a href="{@docRoot}reference/adb.html">Using adb</a> for details.</dd> + +<dt>Getting screen captures from the emulator<a name="screencaps" id="screencaps"></a></dt> +<dd> Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator.</dd> + + +<a name="debughelpers"></a> + +<dt>Using debugging helper classes</dt> + +<dd>Android provides debug helper classes such as {@link android.util.Log + util.Log} and {@link android.os.Debug} for your convenience. </dd> +</dl> +<a name="building"></a> + +<h2>Building and Installing an Android Application</h2> +<p>Android requires custom build tools to be able to properly build the resource + files and other parts of an Android application. Because of this, you must have + a specialized build environment for your application. </p> +<p>Custom + Android compilation steps include compiling the XML and other resource files, and creating + the proper output format. A compiled Android application is an .apk file, which + is a compressed file containing <a href="{@docRoot}reference/glossary.html">.dex</a> files, resource files, raw data files, and + other files. You can create a properly structured Android project either from +scratch, or from existing source files. </p> +<p>Android does not currently support development of third party applications in native code (C/C++).</p> +<p><strong>The recommended way</strong> to develop an Android + application is to <a href="#developingwitheclipse">use Eclipse with the Android plugin</a>, + which provides support for building, running, and debugging Android applications. </p> +<p><strong>If you have another IDE</strong>, <a href="#otherides">Android + provides tools for other IDEs</a> to build and debug Android applications, + but they are not as integrated. </p> + +<a name="uninstalling" id="uninstalling"></a> + + <h2>Removing an Android Application</h2> + + <p>To remove an application that you have installed on the emulator, you will + need to <a href="{@docRoot}reference/adb.html">run adb</a> and delete the .apk + file you sent to the emulator when you installed it. Use <code>adb + shell</code> to drop into a shell on the device as described in the linked + topic, navigate to <code>data/app/</code>, and then remove the file using + <code>rm <em>your_app</em>.apk</code>. </p> + +<a name="tips" id="tips"></a> + + <h2>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}reference/ddms.html">DDMS</a>). </p> + +<h3>Adding JUnit test classes</h3> + +<p>In Eclipse/ADT, you can add JUnit test classes to your application. However, you need to set up a custom JUnit configuration before your tests will run properly. For detailed information about how to set up the JUnit configuration, see the troubleshooting topic <a href="{@docRoot}kb/troubleshooting.html#addjunit">I can't run a Junit test class in Eclipse</a>.</p> + |