diff options
| -rw-r--r-- | docs/html/guide/developing/debug-tasks.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/debug-tasks.jd | 232 | ||||
| -rw-r--r-- | docs/html/guide/developing/eclipse-adt.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/eclipse-adt.jd | 860 | ||||
| -rw-r--r-- | docs/html/guide/developing/other-ide.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/other-ide.jd | 937 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/aapt.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/aapt.jd | 20 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/avd.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/avd.jd | 447 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/ddms.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/ddms.jd | 251 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/hierarchy-viewer.jd | 94 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/othertools.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/othertools.jd | 95 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/traceview.jd | 319 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 47 |
17 files changed, 112 insertions, 3260 deletions
diff --git a/docs/html/guide/developing/debug-tasks.html b/docs/html/guide/developing/debug-tasks.html new file mode 100644 index 0000000..4e73804 --- /dev/null +++ b/docs/html/guide/developing/debug-tasks.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/debugging/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/debugging/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd deleted file mode 100644 index 8f40b48..0000000 --- a/docs/html/guide/developing/debug-tasks.jd +++ /dev/null @@ -1,232 +0,0 @@ -page.title=Debugging Tasks -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#tools">Tools</a></li> - <li><a href="#additionaldebugging">Debug with Dev Tools</a></li> - <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li> - <li><a href="#toptips">Top Debugging Tips</a></li> - <li><a href="#ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</a></li> - </ol> -</div> -</div> - -<p>This document offers some helpful guidance to debugging applications on Android. - - -<h2 id="tools">Tools</h2> - -<p>The Android SDK includes a set of tools to help you debug and profile -your applications. Here are some tools that you'll use most often:</p> - -<dl> - <dt><strong><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge -(ADB)</a></strong></dt> - <dd>Provides various device management capabilities, including - moving and syncing files to the emulator, forwarding ports, and running a UNIX - shell on the emulator.</dd> - <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server -(DDMS)</a></strong></dt> - <dd>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.</dd> - </dd> - <dt><strong><a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a></strong></dt> - <dd>A graphical viewer that displays trace file data for method calls and times saved by - your application, which can help you profile the performance of your application.</dd> - <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt> - <dd>Dumps a log of system - messages. The messages include a stack trace when the device throws an error, - as well as {@link android.util.Log} messages you've written from your application. To run - logcat, execute <code>adb logcat</code> from your Android SDK {@code platform-tools/} -directory or, from DDMS, select <strong>Device > Run - logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT plugin for -Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from -<strong>Window > Show View > Other > Android > Logcat</strong>. - <p>{@link android.util.Log} is a logging - class you can use to print out messages to the logcat. You can read messages - in real time if you run logcat on DDMS (covered next). Common logging methods include: - {@link android.util.Log#v(String,String)} (verbose), {@link - android.util.Log#d(String,String)} (debug), {@link android.util.Log#i(String,String)} - (information), {@link android.util.Log#w(String,String)} (warning) and {@link - android.util.Log#e(String,String)} (error). For example:</p> -<pre class="no-pretty-print"> -Log.i("MyActivity", "MyClass.getView() — get item number " + position); -</pre> - <p>The logcat will then output something like:</p> -<pre class="no-pretty-print"> -I/MyActivity( 1557): MyClass.getView() — get item number 1 -</pre> - <p>Logcat is also the place to look when debugging a web page in the Android Browser app. See -<a href="#DebuggingWebPages">Debugging Web Pages</a> below.</p> -</dl> - -<p>For more information about all the development tools provided with the Android SDK, see the <a -href="{@docRoot}guide/developing/tools/index.html">Tools</a> document.</p> - -<p>In addition to the above tools, you may also find the following useful for debugging: -<dl> - <dt><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse ADT -plugin</strong></a></dt> - <dd>The ADT Plugin for Eclipse integrates a number of the Android development tools (ADB, DDMS, -logcat output, and other functionality), so that you won't work with them directly but will utilize -them through the Eclipse IDE.</dd> - <dt><strong>Developer Settings in the Dev Tools app</strong></dt> - <dd>The Dev Tools application included in the emulator system image exposes several settings - that provide useful information such as CPU usage and frame rate. See <a -href="#additionaldebugging">Debugging and Testing with Dev Tools</a> below.</dd> -</dl> - -<h2 id="additionaldebugging">Debugging and Testing with Dev Tools</h2> - -<p>With the Dev Tools application, you can enable a number of settings on your device that will -make it easier to test and debug your applications.</p> - -<p>The Dev Tools application is installed by default -on all system images included with the SDK, so you can use it with the Android Emulator. If you'd -like to install the Dev Tools application on a real development device, you can copy the -application from your emulator and then install it on your device using ADB. To copy the -application from a running emulator, execute: -</p> -<pre> -adb -e pull /system/app/Development.apk ./Development.apk -</pre> -<p>This copies the .apk file into the current directory. Then install it on your connected device -with:</p> -<pre> -adb -d install Development.apk -</pre> - -<p>To get started, launch the Dev Tools application and -select Development Settings. This will open the Development Settings page with the -following options (among others):</p> - -<dl> - <dt><strong>Debug app</strong></dt> - <dd>Lets you select the application to debug. You do not need to set this to attach a debugger, - but setting this value has two effects: - <ul> - <li>It will prevent Android from throwing an error if you pause on - a breakpoint for a long time while debugging.</li> - <li>It will enable you to select the <em>Wait for Debugger</em> option - to pause application startup until your debugger attaches (described - next). </li> - </ul> - </dd> - <dt><strong>Wait for debugger</strong></dt> - <dd>Blocks the selected application from loading until a debugger attaches. This - way you can set a breakpoint in onCreate(), which is important to debug - the startup process of an Activity. When you change this option, any - currently running instances of the selected application will be killed. - In order to check this box, you must have selected a debug application - as described in the previous option. You can do the same thing by adding - {@link android.os.Debug#waitForDebugger()} to your code.</dd> - <dt><strong>Show screen updates</strong></dt> - <dd>Flashes a momentary pink rectangle on any screen sections that are being - redrawn. This is very useful for discovering unnecessary screen drawing.</dd> - <dt><strong>Immediately destroy activities</strong></dt> - <dd>Tells the - system to destroy an activity as soon as it is stopped (as if Android had to - reclaim memory). This is very useful for testing the {@link android.app.Activity#onSaveInstanceState} - / {@link android.app.Activity#onCreate(android.os.Bundle)} code path, which would - otherwise be difficult to force. Choosing this option will probably reveal - a number of problems in your application due to not saving state.</dd> - <dt><strong>Show CPU usage</strong></dt> - <dd>Displays CPU meters at the - top of the screen, showing how much the CPU is being used. The top red bar - shows overall CPU usage, and the green bar underneath it shows the CPU time - spent in compositing the screen. <em>Note: You cannot turn this feature off - once it is on, without restarting the emulator.</em> </dd> - <dt><strong>Show background</strong></dt> - <dd>Displays a background pattern - when no activity screens are visible. This typically does not happen, but - can happen during debugging.</dd> -</dl> - -<p>These settings will be remembered across emulator restarts.</p> - -<h2 id="DebuggingWebPages">Debugging Web Pages</h2> - -<p>See the <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a> document.</p> - - -<h2 id="toptips">Top Debugging Tips</h2> - -<dl> -<dt><strong>Dump the stack trace</strong></dt> -<dd>To obtain a stack dump from emulator, you can log -in with <code>adb shell</code>, use "ps" to find the process you -want, and then "kill -3 ". The stack trace appears in the log file. -</dd> - -<dt><strong>Display useful info on the emulator screen</strong></dt> -<dd>The device can display useful information such as CPU usage or highlights -around redrawn areas. Turn these features on and off in the developer settings -window as described in <a href="#additionaldebugging">Setting debug and test -configurations on the emulator</a>. -</dd> - -<dt><strong>Get system state information from the emulator (dumpstate)</strong></dt> -<dd>You can access dumpstate information from the Dalvik Debug Monitor Service -tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and -dumpstate</a> on the adb topic page.</dd> - -<dt><strong>Get application state information from the emulator (dumpsys)</strong></dt> -<dd>You can access dumpsys information from the Dalvik Debug Monitor Service -tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and -dumpstate</a> on the adb topic page.</dd> - -<dt><strong>Get wireless connectivity information</strong></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><strong>Log trace data</strong></dt> -<dd>You can log method calls and other tracing data in an activity by calling -{@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a -href="{@docRoot}guide/developing/tools/traceview.html">Running the Traceview Debugging -Program</a> for details. </dd> - -<dt><strong>Log radio data</strong></dt> -<dd>By default, radio information is not logged to the system (it is a lot of -data). However, you can enable radio logging using the following commands: - -<pre class="no-pretty-print"> -adb shell -logcat -b radio -</pre> -</dd> - -<dt><strong>Capture screenshots</strong></dt> -<dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select -<strong>Device > Screen capture</strong>.</dd> - -<dt><strong>Use debugging helper classes</strong></dt> -<dd>Android provides debug helper classes such as {@link android.util.Log - util.Log} and {@link android.os.Debug} for your convenience. </dd> -</dl> - -<p>Also see the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document -for answers to some common developing and debugging issues.</p> - - -<h2 id="ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</h2> - -<p>DDMS will assign a specific debugging port to every virtual machine that it - finds on the emulator. You must either attach your IDE to that - port (listed on the Info tab for that VM), or you can use a default port 8700 - to connect to whatever application is currently selected on the list of discovered - virtual machines.</p> -<p>Your IDE should attach to your application running on the emulator, showing you - its threads and allowing you to suspend them, inspect their state, and set breakpoints. - If you selected "Wait for debugger" in the Development settings panel - the application will run when Eclipse connects, so you will need to set any breakpoints - you want before connecting.</p> -<p>Changing either the application being debugged or the "Wait for debugger" - option causes the system to kill the selected application if it is currently - running. You can use this to kill your application if it is in a bad state - by simply going to the settings and toggling the checkbox.</p> diff --git a/docs/html/guide/developing/eclipse-adt.html b/docs/html/guide/developing/eclipse-adt.html new file mode 100644 index 0000000..879a356 --- /dev/null +++ b/docs/html/guide/developing/eclipse-adt.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/projects/projects-eclipse.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/projects/projects-eclipse.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd deleted file mode 100644 index f8d32e7..0000000 --- a/docs/html/guide/developing/eclipse-adt.jd +++ /dev/null @@ -1,860 +0,0 @@ -page.title=Developing In Eclipse, with ADT -@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="#AVD">Creating an AVD</a></li> - <li><a href="#Running">Running Your Application</a> - <ol> - <li><a href="#RunningOnEmulator">Running on the emulator</a></li> - <li><a href="#RunningOnDevice">Running on a device</a></li> - </ol> - </li> - <li><a href="#RunConfig">Creating a Run Configuration</a></li> - <li><a href="#Signing">Setting Up Application Signing</a></li> - <li><a href="#libraryProject">Working with Library Projects</a> - <ol> - <li><a href="#libraryReqts">Development requirements</a></li> - <li><a href="#librarySetup">Setting up a library project</a></li> - <li><a href="#libraryReference">Referencing a library project</a></li> - <li><a href="#considerations">Development considerations</a></li> - <li><a href="#libraryMigrating">Migrating library projects to ADT 0.9.8</a></li> - </ol> - </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 information directly 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 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/eclipse-adt.html#installing">Installing -the ADT Plugin</a>.</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/eclipse-adt.html#updating">Updating Your ADT Plugin</a>.</p> - -<p class="note"><strong>Note:</strong> This guide assumes you are using the latest version of -the ADT plugin. 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 id="CreatingAProject">Creating an Android Project</h2> - -<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 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.</p> - <p class="note"><strong>Note:</strong> You can change your the Build Target for your - project at any time: Right-click the project in the Package Explorer, select - <strong>Properties</strong>, select <strong>Android</strong> and then check - the desired Project Target.</p> - </li> - <li>Under Properties, fill in all necessary fields. - <ul> - <li>Enter an <em>Application name</em>. This is the human-readable title for your - application — the name that will appear on the Android device.</li> - <li>Enter a <em>Package name</em>. This is the package namespace (following the same rules - as for packages in the Java programming language) where all your source code - will reside.</li> - <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name - for your main Activity class.</li> - <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates - the minimum API Level required to properly run your application. - Entering this here automatically sets the <code>minSdkVersion</code> attribute in the - <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> - of your Android Manifest file. If you're unsure of the appropriate <a -href="{@docRoot}guide/appendix/api-levels.html">API Level</a> to use, - copy the API Level listed for the Build Target you selected in the Target tab.</li> - </ul> - </li> - </ul> - </li> - <li>Click <strong>Finish</strong>.</li> -</ol> - -<p class="note"><strong>Tip:</strong> -You can also start the New Project Wizard from the <em>New</em> icon in the toolbar.</p> - -<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. </dd> - <dt><code>res/</code></dt> - <dd>A folder for your application resources, such as drawable files, layout files, string - values, etc. See - <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>.</dd> - <dt><code>AndroidManifest.xml</code></dt> - <dd>The Android Manifest for your project. See - <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml - File</a>.</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="AVD">Creating an AVD</h2> - -<p>An Android Virtual Device (AVD) is a device configuration for the emulator that -allows you to model real world devices. In order to run an instance of the emulator, you must create -an AVD.</p> - -<p>To create an AVD from Eclipse:</p> - -<ol> - <li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and -AVD Manager icon in the Eclipse toolbar.</p> - </li> - <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click -<strong>New</strong> to create a new AVD.</li> - <li>Fill in the details for the AVD. - <p>Give it a name, a platform target, an SD card size, and - a skin (HVGA is default).</p> - <p class="note"><strong>Note:</strong> Be sure to define - a target for your AVD that satisfies your application's Build Target (the AVD - platform target must have an API Level equal to or greater than the API Level that your -application compiles against).</p> - </li> - <li>Click <strong>Create AVD</strong>.</li> -</ol> - -<p>Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or -launch an emulator with the AVD by selecting a device and clicking <strong>Start</strong>.</p> - -<p>For more information about AVDs, read the -<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> -documentation.</p> - - -<h2 id="Running">Running Your Application</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Use the Emulator to Test Different Configurations</h2> -<p>Create multiple AVDs that each define a different device configuration with which your -application is compatible, then launch each AVD into a new emulator from the SDK and AVD Manager. -Set the target mode in your app's run configuration to manual, so that when you run your -application, you can select from the available virtual devices.</p> -</div> -</div> - -<p>Running your application from Eclipse will usually require just a couple clicks, whether you're -running it on the emulator or on an attached device. The information below describes how to get -set up and run your application from Eclipse.</p> - -<h3 id="RunningOnEmulator">Running on the emulator</h3> - -<p>Before you can run your application on the Android Emulator, -you <strong>must</strong> <a href="#AVD">create an AVD</a>.</p> - -<p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or -<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin -will automatically create a default launch configuration for the project. Eclipse will then perform -the following:</p> - -<ol> - <li>Compile the project (if there have been changes since the last build).</li> - <li>Create a default 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 run configurations use an "automatic target" mode for - selecting a device target. For information on how automatic target mode selects a - deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual - target modes</a> below.</p> - </li> -</ol> - -<p>If 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="#RunConfig">Creating a Run Configuration</a> for information.</p> - -<p>Be certain to create multiple AVDs upon which to test your application. You should have one AVD -for each platform and screen type with which your application is compatible. For -instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should -create an AVD for each platform equal to and greater than 1.5 and an AVD for each <a -href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test -your application on each one.</p> - - -<h3 id="RunningOnDevice">Running on a device</h3> - -<p>Before you can run your application on a device, you must perform some basic setup for your -device:</p> - -<ul> - <li>Declare your application as debuggable in your manifest</li> - <li>Enable USB Debugging on your device</li> - <li>Ensure that your development computer can detect your device when connected via USB</li> -</ul> -<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for -Development</a> for more information.</p> - -<p>Once set up and your device is connected via USB, install your application on the device by -selecting <strong>Run</strong> > <strong>Run</strong> (or -<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse menu bar.</p> - - - -<h2 id="RunConfig">Creating a Run Configuration</h2> - -<p>The run configuration specifies the project to run, the Activity -to start, the emulator or connected device to use, and so on. When you first run a project -as an <em>Android Application</em>, ADT will automatically create a run configuration. -The default run configuration will -launch the default project Activity and use automatic target mode for device selection -(with no preferred AVD). If the default settings don't suit your project, you can -customize the launch configuration or even create a new.</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="#AutoAndManualTargetModes">Automatic and manual target - modes</a>).</p> - <p>You can specify any emulator options to the Additional Emulator Command - Line Options field. For example, you could add <code>-scale 96dpi</code> to - scale the AVD's screen to an accurate size, based on the dpi of your - computer monitor. For a full list of emulator options, see the <a - href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> -document.</p> - </li> -</ol> - - -<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3> - -<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to -select an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p> - -<ol> - <li>If there's a device or emulator already running and its AVD configuration - meets the requirements of the application's build target, the application is installed - and run upon it.</li> - <li>If there's more than one device or emulator running, each of which meets the requirements - of the build target, a "device chooser" is shown to let you select which device to use.</li> - <li>If there are no devices or emulators running that meet the requirements of the build target, - ADT looks at the available AVDs. If 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>However, if a "preferred AVD" is selected in the run configuration, then the application -will <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator -will be launched.</p> - -<p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" -is presented every time that your application is run, so that you can select which AVD to use.</p> - - -<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> - -<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="libraryProject">Working with Library Projects</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Library project example code</h2> - -<p>The SDK includes an example application called TicTacToeMain that shows how a -dependent application can use code and resources from an Android Library -project. The TicTacToeMain application uses code and resources from an example -library project called TicTacToeLib. - -<p style="margin-top:1em;">To download the sample applications and run them as -projects in your environment, use the <em>Android SDK and AVD Manager</em> to -download the "Samples for SDK API 8" component into your SDK. </p> - -<p style="margin-top:1em;">For more information and to browse the code of the -samples, see the <a -href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain -application</a>.</p> -</div> -</div> - -<p>An Android <em>library project</em> is a development project that holds -shared Android source code and resources. Other Android application projects can -reference the library project and, at build time, include its compiled sources -in their <code>.apk</code> files. Multiple application projects can reference -the same library project and any single application project can reference -multiple library projects. </p> - -<p>If you have source code and resources that are common to multiple application -projects, you can move them to a library project so that it is easier to -maintain across applications and versions. Here are some common scenarios in -which you could make use of library projects: </p> - -<ul> -<li>If you are developing multiple related applications that use some of the -same components, you could move the redundant components out of their respective -application projects and create a single, reuseable set of the same components -in a library project. </li> -<li>If you are creating an application that exists in both free and paid -versions, you could move the part of the application that is common to both versions -into a library project. The two dependent projects, with their different package -names, will reference the library project and provide only the difference -between the two application versions.</li> -</ul> - -<p>Structurally, a library project is similar to a standard Android application -project. For example, it includes a manifest file at the project root, as well -as <code>src/</code>, <code>res/</code> and similar directories. The project can -contain the same types of source code and resources as a standard -Android project, stored in the same way. For example, source code in the library -project can access its own resources through its <code>R</code> class. </p> - -<p>However, a library project differs from an standard Android application -project in that you cannot compile it directly to its own <code>.apk</code> or -run it on the Android platform. Similarly, you cannot export the library project -to a self-contained JAR file, as you would do for a true library. Instead, you -must compile the library indirectly, by referencing the library from a dependent -application's build path, then building that application. </p> - -<p>When you build an application that depends on a library project, the SDK -tools compile the library and merge its sources with those in the main project, -then use the result to generate the <code>.apk</code>. In cases where a resource -ID is defined in both the application and the library, the tools ensure that the -resource declared in the application gets priority and that the resource in the -library project is not compiled into the application <code>.apk</code>. This -gives your application the flexibility to either use or redefine any resource -behaviors or values that are defined in any library.</p> - -<p>To organize your code further, your application can add references to -multiple library projects, then specify the relative priority of the resources -in each library. This lets you build up the resources actually used in your -application in a cumulative manner. When two libraries referenced from an -application define the same resource ID, the tools select the resource from the -library with higher priority and discard the other. </p> - -<p>ADT lets you add references to library projects and set their relative -priority from the application project's Properties. As shown in Figure 2, -below, once you've added a reference to a library project, you can use the -<strong>Up</strong> and <strong>Down</strong> controls to change the ordering, -with the library listed at the top getting the higher priority. At build time, -the libraries are merged with the application one at a time, starting from the -lowest priority to the highest. </p> - -<p>Note that a library project cannot itself reference another library project -and that, at build time, library projects are <em>not</em> merged with each -other before being merged with the application. However, note that a library can -import an external library (JAR) in the normal way.</p> - -<p>The sections below describe how to use ADT to set up and manage library your -projects. Once you've set up your library projects and moved code into them, you -can import library classes and resources to your application in the normal way. -</p> - - -<h3 id="libraryReqts">Development requirements</h3> - -<p>Android library projects are a build-time construct, so you can use them to -build a final application <code>.apk</code> that targets any API level and is -compiled against any version of the Android library. </p> - -<p>However, to use library projects, you need to update your development -environment to use the latest tools and platforms, since older releases of the -tools and platforms do not support building with library projects. Specifically, -you need to download and install the versions listed below:</p> - -<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools -and plaforms on which you can develop library projects.</p> - -<table> -<tr> -<th>Component</th> -<th>Minimum Version</th> -</tr> -<tr> -<td>SDK Tools</td> -<td>r6 (or higher)</td> -</tr> -<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr> -<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr> -<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr> -<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr> -<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr> -</table> - -<p>You can download the tools and platforms using the <em>Android SDK and AVD -Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK -Components</a>. To install or update ADT, use the Eclipse Updater as described -in <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a>.</p> - - -<h3 id="librarySetup">Setting up a library project</h3> - -<p>A library project is a standard Android project, so you can create a new one in the -same way as you would a new application project. Specifically, you can use -the New Project Wizard, as described in <a href="#CreatingAProject">Creating an -Android Project</a>, above. </p> - -<p>When you are creating the library project, you can select any application -name, package, and set other fields as needed, as shown in the diagram below. -Click Finish to create the project in the workspace.</p> - -<p>Next, set the project's Properties to indicate that it is a library project:</p> - -<ol> -<li>In the <strong>Package Explorer</strong>, right-click the library project -and select <strong>Properties</strong>.</li> -<li>In the <strong>Properties</strong> window, select the "Android" properties -group at left and locate the <strong>Library</strong> properties at right. </li> -<li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li> -<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li> -</ol> - -<p>The new project is now marked as a library project. You can begin moving -source code and resources into it, as described in the sections below. </p> - -<p>You can also convert an existing application project into a library. To do -so, simply open the Properties for the project and select the "is Library" -checkbox. Other application projects can now reference the existing project as a -library project.</p> - -<img src="{@docRoot}images/developing/adt-props-isLib.png" style="margin:0;padding:0;" /> -<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 1.</strong> -Marking a project as an Android library project. </p> - -<h4>Creating the manifest file</h4> - -<p>A library project's manifest file must declare all of the shared components -that it includes, just as would a standard Android application. For more -information, see the documentation for <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> - -<p>For example, the <a -href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> -example library project declares the Activity <code>GameActivity</code>: </p> - -<pre><manifest> - ... - <application> - ... - <activity android:name="GameActivity" /> - ... - </application> -</manifest></pre> - - -<h3 id="libraryReference">Referencing a library project from an application</h3> - -<p>If you are developing an application and want to include the shared code or -resources from a library project, you can do so easily by adding a reference to -the library project in the application project's Properties.</p> - -<p>To add a reference to a library project, follow these steps: </p> - -<ol> -<li>In the <strong>Package Explorer</strong>, right-click the dependent project -and select <strong>Properties</strong>.</li> -<li>In the <strong>Properties</strong> window, select the "Android" properties group -at left and locate the <strong>Library</strong> properties at right.</li> -<li>Click <strong>Add</strong> to open the <strong>Project Selection</strong> -dialog. </li> -<li>From the list of available library projects, select a project and click -<strong>OK</strong>.</li> -<li>When the dialog closes, click <strong>Apply</strong> in the -<strong>Properties</strong> window.</li> -<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li> -</ol> - -<p>As soon as the Properties dialog closes, Eclipse rebuilds the project, -including the contents of the library project. </p> - -<p>The figure below shows the Properties dialog that lets you add library -references and move them up and down in priority. </p> - -<img src="{@docRoot}images/developing/adt-props-libRef.png" style="margin:0;padding:0;" /> -<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 2.</strong> -Adding a reference to a library project in the properties of an application project. </p> - -<p>If you are adding references to multiple libraries, note that you can set -their relative priority (and merge order) by selecting a library and using the -<strong>Up</strong> and <strong>Down</strong> controls. The tools merge the -referenced libraries with your application starting from lowest priority (bottom -of the list) to highest (top of the list). If more than one library defines the -same resource ID, the tools select the resource from the library with higher -priority. The application itself has highest priority and its resources are -always used in preference to identical resource IDs defined in libraries.</p> - -<h4>Declaring library components in the the manifest file</h4> - -<p>In the manifest file of the application project, you must add declarations -of all components that the application will use that are imported from a library -project. For example, you must declare any <code><activity></code>, -<code><service></code>, <code><receiver></code>, -<code><provider></code>, and so on, as well as -<code><permission></code>, <code><uses-library></code>, and similar -elements.</p> - -<p>Declarations should reference the library components by their fully-qualified -package names, where appropriate. </p> - -<p>For example, the <a -href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> -example application declares the library Activity <code>GameActivity</code> -like this: </p> - -<pre><manifest> - ... - <application> - ... - <activity android:name="com.example.android.tictactoe.library.GameActivity" /> - ... - </application> -</manifest></pre> - -<p>For more information about the manifest file, see the documentation for <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> - - -<h3 id="considerations">Development considerations</h3> - -<p>As you develop your library project and dependent applications, keep the -points listed below in mind.</p> - -<p><strong>Resource conflicts</strong></p> - -<p>Since the tools merge the resources of a library project with those of a -dependent application project, a given resource ID might be defined in both -projects. In this case, the tools select the resource from the application, or -the library with highest priority, and discard the other resource. As you -develop your applications, be aware that common resource IDs are likely to be -defined in more than one project and will be merged, with the resource from the -application or highest-priority library taking precedence.</p> - -<p><strong>Using prefixes to avoid resource conflicts</strong></p> - -<p>To avoid resource conflicts for common resource IDs, consider using a prefix -or other consistent naming scheme that is unique to the project (or is unique -across all projects). </p> - -<p><strong>No export of library project to JAR</strong></p> - -<p>A library cannot be distributed as a binary file (such as a jar file). This -is because the library project is compiled by the main project to use the -correct resource IDs.</p> - -<p><strong>A library project can include a JAR library</strong></p> - -<p>You can develop a library project that itself includes a JAR library, however -you need to manually edit the dependent application project's build path and add -a path to the JAR file. </p> - -<p><strong>A library project can depend on an external JAR library</strong></p> - -<p>You can develop a library project that depends on an external library (for -example, the Maps external library). In this case, the dependent application -must build against a target that includes the external library (for example, the -Google APIs Add-On). Note also that both the library project and the dependent -application must declare the external library their manifest files, in a <a -href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a> -element. </p> - -<p><strong>Library project can not include raw assets</strong></p> - -<p>The tools do not support the use of raw asset files in a library project. -Any asset resources used by an application must be stored in the -<code>assets/</code> directory of the application project -itself.</p> - -<p><strong>Targeting different Android platform versions in library project and -application project</strong></p> - -<p>A library is compiled as part of the dependent application project, so the -API used in the library project must be compatible with the version of the -Android library used to compile the application project. In general, the library -project should use an <a href="{@docRoot}guide/appendix/api-levels.html">API level</a> -that is the same as — or lower than — that used by the application. -If the library project uses an API level that is higher than that of the -application, the application project will fail to compile. It is perfectly -acceptable to have a library that uses the Android 1.5 API (API level 3) and -that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) -project, for instance.</p> - -<p><strong>No restriction on library package name</strong></p> - -<p>There is no requirement for the package name of a library to be the same as -that of applications that use it.</p> - -<p><strong>Multiple R classes in gen/ folder of application project</strong></p> - -<p>When you build the dependent application project, the code of any libraries -is compiled and merged to the application project. Each library has its own -<code>R</code> class, named according to the library's package name. The -<code>R</code> class generated from the resources of the main project and of the -library is created in all the packages that are needed including the main -project’s package and the libraries’ packages.</p> - -<p><strong>Testing a library project</strong></p> - -<p>There are two recommended ways of setting up testing on code and resources in -a library project: </p> - -<ul> -<li>You can set up a <a -href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a> -that instruments an application project that depends on the library project. You -can then add tests to the project for library-specific features.</li> -<li>You can set up a set up a standard application project that depends on the -library and put the instrumentation in that project. This lets you create a -self-contained project that contains both the tests/instrumentations and the -code to test.</li> -</ul> - -<p><strong>Library project storage location</strong></p> - -<p>There are no specific requirements on where you should store a library -project, relative to a dependent application project, as long as the application -project can reference the library project by a relative link. You can place the -library project What is important is that the main project can reference the -library project through a relative link.</p> - -<h3 id="libraryMigrating">Migrating library projects to ADT 0.9.8</h3> - -<p>This section provides information about how to migrate a library project -created with ADT 0.9.7 to ADT 0.9.8 (or higher). The migration is needed only if -you are developing in Eclipse with ADT and assumes that you have also upgraded -to SDK Tools r7 (or higher). </p> - -<p>The way that ADT handles library projects has changed between -ADT 0.9.7 and ADT 0.9.8. Specifically, in ADT 0.9.7, the <code>src/</code> -source folder of the library was linked into the dependent application project -as a folder that had the same name as the library project. This worked because -of two restrictions on the library projects:</p> - -<ul> -<li>The library was only able to contain a single source folder (excluding the -special <code>gen/</code> source folder), and</li> -<li>The source folder was required to have the name <code>src/</code> and be -stored at the root of the project.</li> -</ul> - -<p>In ADT 0.9.8, both of those restrictions were removed. A library project can -have as many source folders as needed and each can have any name. Additionally, -a library project can store source folders in any location of the project. For -example, you could store sources in a <code>src/java/</code> directory. In order -to support this, the name of the linked source folders in the main project are -now called <<em>library-name</em>>_<<em>folder-name</em>> For -example: <code>MyLibrary_src/</code> or <code>MyLibrary_src_java/</code>.</p> - -<p>Additionally, the linking process now flags those folders in order for ADT to -recognize that it created them. This will allow ADT to automatically migrate the -project to new versions of ADT, should they contain changes to the handling of -library projects. ADT 0.9.7 did not flag the linked source folders, so ADT 0.9.8 -cannot be sure whether the old linked folders can be removed safely. After -upgrading ADT to 0.9.8, you will need to remove the old linked folders manually -in a simple two-step process, as described below.</p> - -<p>Before you begin, make sure to create a backup copy of your application or -save the latest version to your code version control system. This ensures that -you will be able to easily revert the migration changes in case there is a -problem in your environment.</p> - -<p>When you first upgrade to ADT 0.9.8, your main project will look as shown -below, with two linked folders (in this example, <code>MyLibrary</code> and -<code>MyLibrary_src</code> — both of which link to -<code>MyLibrary/src</code>. Eclipse shows an error on one of them because they -are duplicate links to a single class.</p> - -<img src="{@docRoot}images/developing/lib-migration-0.png" alt=""> - -<p>To fix the error, remove the linked folder that <em>does not</em> contain the -<code>_src</code> suffix. </p> - -<ol> -<li>Right click the folder that you want to remove (in this case, the -<code>MyLibrary</code> folder) and choose <strong>Build Path</strong> > -<strong>Remove from Build Path</strong>, as shown below.</li> - -<img src="{@docRoot}images/developing/lib-migration-1.png" style="height:600px" -alt=""> - -<li>Next, When asked about unlinking the folder from the project, select -<strong>Yes</strong>, as shown below.</li> - -<img src="{@docRoot}images/developing/lib-migration-2.png" alt=""> -</ol> - -<p>This should resolve the error and migrate your library project to the new -ADT environment. </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.html b/docs/html/guide/developing/other-ide.html new file mode 100644 index 0000000..41dba05 --- /dev/null +++ b/docs/html/guide/developing/other-ide.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/projects/projects-cmdline.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/projects/projects-cmdline.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd deleted file mode 100644 index d309f47..0000000 --- a/docs/html/guide/developing/other-ide.jd +++ /dev/null @@ -1,937 +0,0 @@ -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="#AVD">Creating an AVD</a></li> - <li><a href="#Running">Running Your Application</a> - <ol> - <li><a href="#RunningOnEmulator">Running on the emulator</a></li> - <li><a href="#RunningOnDevice">Running on a device</a></li> - </ol> - </li> - <li><a href="#libraryProject">Working with Library Projects</a> - <ol> - <li><a href="#libraryReqts">Development requirements</a></li> - <li><a href="#librarySetup">Setting up a library project</a></li> - <li><a href="#libraryReference">Referencing a library project</a></li> - <li><a href="#depAppBuild">Building a dependent application project</a></li> - <li><a href="#considerations">Development considerations</a></li> - </ol> - </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 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 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 id="EssentialTools">Essential Tools</h2> - -<p>When developing in IDEs or editors other than Eclipse, you'll require -familiarity with the following Android SDK tools:</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> - - -<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><target_ID></em> \ ---name <em><your_project_name></em> \ ---path <em>path/to/your/project</em> \ ---activity <em><your_activity_name></em> \ ---package <em><your_package_namespace></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>name</code> is the name for your project. This is optional. If provided, this name will -be used - for your .apk filename when you build your application.</li> - <li><code>path</code> is the location of your project directory. If the directory does not exist, - it will be created for you.</li> - <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This -class file - will be created for you inside - -<code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code> -. - This will also be used for your .apk filename unless you provide a the <code>name</code>.</li> - <li><code>package</code> is the package namespace for your project, following the same rules as -for - packages in the Java programming language.</li> -</ul> - -<p>Here's an example:</p> -<pre> -android create project \ ---target 1 \ ---name MyAndroidApp \ ---path ./MyAndroidAppProject \ ---activity MyAndroidAppActivity \ ---package com.example.myandroid -</pre> - -<p>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> - 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 override default build settings used by Ant and provide a pointer to your keystore and key -alias - so that the build tools can sign your application when built in release mode.</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>Once you've created your project, you're ready to begin development. -You can move your project folder wherever you want for development, but keep in mind -that you must use the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> -(adb) — located in the SDK <code>platform-tools/</code> directory — to send your -application -to the emulator (discussed later). So you need access between your project solution and -the <code>platform-tools/</code> folder.</p> - -<p class="caution"><strong>Caution:</strong> You should refrain from moving the -location of the SDK directory, because this will break the build scripts. (They -will need to be manually updated to reflect the new SDK location before they will -work again.)</p> - - -<h3 id="UpdatingAProject">Updating a project</h3> - -<p>If you're upgrading a project from an older version of the Android SDK or want to create -a new project from existing code, use the -<code>android update project</code> command to update the project to the new development -environment. You can also use this command to revise the build target of an existing project -(with the <code>--target</code> option) and the project name (with the <code>--name</code> -option). The <code>android</code> tool will generate any files and -folders (listed in the previous section) that are either missing or need to be updated, -as needed for the Android project.</p> - -<p>To update an existing Android project, open a command-line -and navigate to the <code>tools/</code> directory of your SDK. Now run:</p> -<pre> -android update project --name <em><project_name></em> --target <em><target_ID></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> - <li><code>name</code> is the name for the project. This is optional—if you're not - changing the project name, you don't need this.</li> -</ul> - -<p>Here's an example:</p> -<pre> -android update project --name MyApp --target 2 --path ./MyAppProject -</pre> - - -<h2 id="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 an emulator or device. There are two ways to do this: -with a <em>debug key</em> (for immediate testing on an emulator or development device) -or with a <em>private key</em> (for application distribution).</p> - -<p>The Android build tools help you get started by automatically signing your .apk -files with a debug key at build time. This means -that you can compile your application and install it on the emulator without -having to generate your own private key. However, please note that if you intend -to publish your application, you <strong>must</strong> sign the application with your -own private key, rather than the debug key generated by the SDK tools. </p> - -<p>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:\Progra~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 and optimize the package with -{@code zipalign}. 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 debug .apk file inside the project <code>bin/</code> - directory, named <code><em><your_project_name></em>-debug.apk</code>. The file - is already signed with the debug key and has been aligned with {@code zipalign}.</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>Before you start building your application in release mode, be aware that you must sign -the resulting application package with your private key, and should then align it using the -{@code zipalign} tool. There are two approaches to building in release mode: -build an unsigned package in release mode and then manually sign and align -the package, or allow the build script -to sign and align the package for you.</p> - -<h4 id="ManualReleaseMode">Build unsigned</h4> - -<p>If you build your application <em>unsigned</em>, then you will need to -manually sign and align the package.</p> - -<p>To build an <em>unsigned</em> .apk in release mode:</p> - -<ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - <li>Use Ant to compile your project in release mode: - <pre>ant release</pre> - </li> -</ol> - -<p>This creates your Android application .apk file inside the project <code>bin/</code> -directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p> - -<p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point -and can't be installed until signed with your private key.</p> - -<p>Once you have created the unsigned .apk, your next step is to sign the .apk -with your private key and then align it with {@code zipalign}. To complete this procedure, -read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> - -<p>When your .apk has been signed and aligned, it's ready to be distributed to end-users.</p> - -<h4 id="AutoReleaseMode">Build signed and aligned</h4> - -<p>If you would like, you can configure the Android build script to automatically -sign and align your application package. To do so, you must provide the path to your keystore -and the name of your key alias in your project's {@code build.properties} file. With this -information provided, the build script will prompt you for your keystore and alias password -when you build in release mode and produce your final application package, which will be ready -for distribution.</p> - -<p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that -you enter during the build process <strong>will be visible</strong>. If you are -concerned about your keystore and alias password being visible on screen, then you -may prefer to perform the application signing manually, via Jarsigner (or a similar tool). To -instead -perform the signing procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then -continue -with <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> - -<p>To specify your keystore and alias, open the project {@code build.properties} file (found in the -root of the project directory) and add entries for {@code key.store} and {@code key.alias}. -For example:</p> - -<pre> -key.store=path/to/my.keystore -key.alias=mykeystore -</pre> - -<p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p> - -<ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - <li>Use Ant to compile your project in release mode: - <pre>ant release</pre> - </li> - <li>When prompted, enter you keystore and alias passwords. - <p class="caution"><strong>Caution:</strong> As described above, - your password will be visible on the screen.</p> - </li> -</ol> - -<p>This creates your Android application .apk file inside the project <code>bin/</code> -directory, named <code><em><your_project_name></em>-release.apk</code>. -This .apk file has been signed with the private key specified in -{@code build.properties} and aligned with {@code zipalign}. It's ready for -installation and distribution.</p> - - -<h4>Once built and signed in release mode</h4> - -<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="AVD">Creating an AVD</h2> - -<p>An Android Virtual Device (AVD) is a device configuration for the emulator that -allows you to model real world devices. In order to run an instance of the emulator, you must create -an AVD.</p> - -<p>To create an AVD using the SDK tools:</p> - -<ol> - <li>Navigate to your SDK's <code>tools/</code> directory and execute the {@code android} -tool with no arguments: - <pre>android</pre> - <p>This will launch the SDK and AVD Manager GUI.</p> - </li> - <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click -<strong>New</strong> - to create a new AVD.</li> - <li>Fill in the details for the AVD. - <p>Give it a name, a platform target, an SD card size, and - a skin (HVGA is default).</p> - <p class="note"><strong>Note:</strong> Be sure to define - a target for your AVD that satisfies your application's build target (the AVD - platform target must have an API Level equal to or greater than the API Level that your -application compiles against).</p> - </li> - <li>Click <strong>Create AVD</strong>.</li> -</ol> - -<p>Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or -launch an emulator with the AVD by clicking <strong>Start</strong>.</p> - -<p>For more information about AVDs, read the -<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> -documentation.</p> - - -<h2 id="Running">Running Your Application</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Use the Emulator to Test Different Configurations</h2> -<p>Create multiple AVDs that each define a different device configuration with which your -application is compatible, then launch each AVD into a new emulator from the SDK and AVD Manager. -Set the target mode in your app's run configuration to manual, so that when you run your -application, you can select from the available virtual devices.</p> -</div> -</div> - -<p>Running your application on a virtual or real device takes just a couple steps. Remember to -first <a href="#Building">build your application</a>.</p> - -<h3 id="RunningOnEmulator">Running on the emulator</h3> - -<p>Before you can run your application on the Android Emulator, -you must <a href="#AVD">create an AVD</a>.</p> - -<p>To run your application:</p> -<ol> - <li><strong>Open the SDK and AVD Manager and launch a virtual device</strong></li> - <p>From your SDK's <code>tools/</code> directory, execute the {@code android} tool with no -arguments: - <pre>android</pre> - <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p> - </li> - - <li><strong>Install your application</strong> - <p>From your SDK's <code>platform-tools/</code> directory, install the {@code .apk} on the -emulator: - <pre>adb install <em><path_to_your_bin></em>.apk</pre> - <p>Your APK file (signed with either a release or debug key) is in your project {@code bin/} -directory after you <a href="#Building">build your application</a>.</p> - <p>If there is more than one emulator running, you must specify the emulator upon which to -install the application, by its serial number, with the <code>-s</code> option. For example:</p> - <pre>adb -s emulator-5554 install <em>path/to/your/app</em>.apk</pre> - <p>To see a list of available device serial numbers, execute {@code adb devices}.</p> - </li> -</ol> - -<p>If you don't see your application on the emulator. Try closing the emulator and launching the -virtual device again from the SDK and AVD Manager. Sometimes when you install an 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>Be certain to create multiple AVDs upon which to test your application. You should have one AVD -for each platform and screen type with which your application is compatible. For -instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should -create an AVD for each platform equal to and greater than 1.5 and an AVD for each <a -href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test -your application on each one.</p> - -<p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, -you can build your application and install it on the emulator in one simple step. -Navigate to the root of your project directory and use Ant to compile the project -with <em>install mode</em>: -<code>ant install</code>. This will build your application, sign it with the debug key, -and install it on the currently running emulator.</p> - - -<h3 id="RunningOnDevice">Running on a device</h3> - -<p>Before you can run your application on a device, you must perform some basic setup for your -device:</p> - -<ul> - <li>Declare your application as debuggable in your manifest</li> - <li>Enable USB Debugging on your device</li> - <li>Ensure that your development computer can detect your device when connected via USB</li> -</ul> -<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for -Development</a> for more information.</p> - -<p>Once your device is set up and connected via USB, navigate to your -SDK's <code>platform-tools/</code> directory and install the <code>.apk</code> on the device: - <pre>adb -d install <em>path/to/your/app</em>.apk</pre> - <p>The {@code -d} flag specifies that you want to use the attached device (in case you also -have an emulator running).</p> - -<p>For more information on the tools used above, please see the following documents:</p> -<ul> - <li><a href="{@docRoot}guide/developing/tools/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="libraryProject">Working with Library Projects</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Library project example code</h2> - -<p>The SDK includes an example application called TicTacToeMain that shows how a -dependent application can use code and resources from an Android Library -project. The TicTacToeMain application uses code and resources from an example -library project called TicTacToeLib. - -<p style="margin-top:1em;">To download the sample applications and run them as -projects in your environment, use the <em>Android SDK and AVD Manager</em> to -download the "Samples for SDK API 8" component into your SDK. </p> - -<p style="margin-top:1em;">For more information and to browse the code of the -samples, see the <a -href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain -application</a>.</p> -</div> -</div> - -<p>An Android <em>library project</em> is a development project that holds -shared Android source code and resources. Other Android application projects can -reference the library project and, at build time, include its compiled sources -in their <code>.apk</code> files. Multiple application projects can reference -the same library project and any single application project can reference -multiple library projects. </p> - -<p>If you have source code and resources that are common to multiple application -projects, you can move them to a library project so that it is easier to -maintain across applications and versions. Here are some common scenarios in -which you could make use of library projects: </p> - -<ul> -<li>If you are developing multiple related applications that use some of the -same components, you could move the redundant components out of their respective -application projects and create a single, reuseable set of the same components -in a library project. </li> -<li>If you are creating an application that exists in both free and paid -versions, you could move the part of the application that is common to both versions -into a library project. The two dependent projects, with their different package -names, will reference the library project and provide only the difference -between the two application versions.</li> -</ul> - -<p>Structurally, a library project is similar to a standard Android application -project. For example, it includes a manifest file at the project root, as well -as <code>src/</code>, <code>res/</code> and similar directories. The project can -contain the same types of source code and resources as a standard -Android project, stored in the same way. For example, source code in the library -project can access its own resources through its <code>R</code> class. </p> - -<p>However, a library project differs from an standard Android application -project in that you cannot compile it directly to its own <code>.apk</code> or -run it on the Android platform. Similarly, you cannot export the library project -to a self-contained JAR file, as you would do for a true library. Instead, you -must compile the library indirectly, by referencing the library from a dependent -application's build path, then building that application. </p> - -<p>When you build an application that depends on a library project, the SDK -tools compile the library and merge its sources with those in the main project, -then use the result to generate the <code>.apk</code>. In cases where a resource -ID is defined in both the application and the library, the tools ensure that the -resource declared in the application gets priority and that the resource in the -library project is not compiled into the application <code>.apk</code>. This -gives your application the flexibility to either use or redefine any resource -behaviors or values that are defined in any library.</p> - -<p>To organize your code further, your application can add references to -multiple library projects, then specify the relative priority of the resources -in each library. This lets you build up the resources actually used in your -application in a cumulative manner. When two libraries referenced from an -application define the same resource ID, the tools select the resource from the -library with higher priority and discard the other. - -<p>Once you've have added references, the tools let you set their relative -priority by editing the application project's build properties. At build time, -the tools merge the libraries with the application one at a time, starting from -the lowest priority to the highest. </p> - -<p>Note that a library project cannot itself reference another library project -and that, at build time, library projects are <em>not</em> merged with each -other before being merged with the application. However, note that a library can -import an external library (JAR) in the normal way.</p> - -<p>The sections below describe how to use ADT to set up and manage library your -projects. Once you've set up your library projects and moved code into them, you -can import library classes and resources to your application in the normal way. -</p> - - -<h3 id="libraryReqts">Development requirements</h3> - -<p>Android library projects are a build-time construct, so you can use them to -build a final application <code>.apk</code> that targets any API level and is -compiled against any version of the Android library. </p> - -<p>However, to use library projects, you need to update your development -environment to use the latest tools and platforms, since older releases of the -tools and platforms do not support building with library projects. Specifically, -you need to download and install the versions listed below:</p> - -<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools -and plaforms on which you can develop library projects.</p> - -<table> -<tr> -<th>Component</th> -<th>Minimum Version</th> -</tr> -<tr> -<td>SDK Tools</td> -<td>r6 (or higher)</td> -</tr> -<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr> -<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr> -<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr> -<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr> -<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr> -</table> - -<p>You can download the tools and platforms using the <em>Android SDK and AVD -Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK -Components</a>.</p> - - -<h3 id="librarySetup">Setting up a new library project</h3> - -<p>A library project is a standard Android project, so you can create a new one in the -same way as you would a new application project. Specifically, you can use -the <code>android</code> tool to generate a new library project with all of the -necessary files and folders. </p> - -<h4>Creating a library project</h4> - -<p>To create a new library project, navigate to the <code><sdk>/tools/</code> directory -and use this command:</p> - -<pre class="no-pretty-print" style="color:black"> -android create lib-project --name <em><your_project_name></em> \ ---target <em><target_ID></em> \ ---path <em>path/to/your/project</em> \ ---package <em><your_library_package_namespace></em> -</pre> - -<p>The <code>create lib-project</code> command creates a standard project -structure that includes preset property that indicates to the build system that -the project is a library. It does this by adding this line to the project's -<code>default.properties</code> file: </p> - -<pre class="no-pretty-print" style="color:black">android.library=true</pre> - -<p>Once the command completes, the library project is created and you can begin moving -source code and resources into it, as described in the sections below.</p> - -<p>If you want to convert an existing application project to a library project, -so that other applications can use it, you can do so by adding a the -<code>android.library=true</code> property to the application's -<code>default.properties</code> file. </p> - -<h4>Creating the manifest file</h4> - -<p>A library project's manifest file must declare all of the shared components -that it includes, just as would a standard Android application. For more -information, see the documentation for <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> - -<p>For example, the <a -href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> -example library project declares the Activity <code>GameActivity</code>: </p> - -<pre><manifest> - ... - <application> - ... - <activity android:name="GameActivity" /> - ... - </application> -</manifest></pre> - -<h4>Updating a library project</h4> - -<p>If you want to update the build properties (build target, location) of the -library project, use this command: </p> - -<pre> -android update lib-project \ ---target <em><target_ID></em> \ ---path <em>path/to/your/project</em> -</pre> - - -<h3 id="libraryReference">Referencing a library project from an application</h3> - -<p>If you are developing an application and want to include the shared code or -resources from a library project, you can do so easily by adding a reference to -the library project in the application project's build properties.</p> - -<p>To add a reference to a library project, navigate to the <code><sdk>/tools/</code> directory -and use this command:</p> - -<pre> -android update lib-project \ ---target <em><target_ID></em> \ ---path <em>path/to/your/project</em> ---library <em>path/to/library_projectA</em> -</pre> - -<p>This command updates the application project's build properties to include a -reference to the library project. Specifically, it adds an -<code>android.library.reference.<em>n</em></code> property to the project's -<code>default.properties</code> file. For example: </p> - -<pre class="no-pretty-print" style="color:black"> -android.library.reference.1=path/to/library_projectA -</pre> - -<p>If you are adding references to multiple libraries, note that you can set -their relative priority (and merge order) by manually editing the -<code>default.properties</code> file and adjusting the each reference's -<code>.<em>n</em></code> index as appropriate. For example, assume these -references: </p> - -<pre class="no-pretty-print" style="color:black"> -android.library.reference.1=path/to/library_projectA -android.library.reference.2=path/to/library_projectB -android.library.reference.3=path/to/library_projectC -</pre> - -<p>You can reorder the references to give highest priority to -<code>library_projectC</code> in this way:</p> - -<pre class="no-pretty-print" style="color:black"> -android.library.reference.2=path/to/library_projectA -android.library.reference.3=path/to/library_projectB -android.library.reference.1=path/to/library_projectC -</pre> - -<p>Note that the <code>.<em>n</em></code> index in the references -must begin at "1" and increase uniformly without "holes". References -appearing in the index after a hole are ignored. </p> - -<p>At build time, the libraries are merged with the application one at a time, -starting from the lowest priority to the highest. Note that a library cannot -itself reference another library and that, at build time, libraries are not -merged with each other before being merged with the application.</p> - - -<h4>Declaring library components in the the manifest file</h4> - -<p>In the manifest file of the application project, you must add declarations -of all components that the application will use that are imported from a library -project. For example, you must declare any <code><activity></code>, -<code><service></code>, <code><receiver></code>, -<code><provider></code>, and so on, as well as -<code><permission></code>, <code><uses-library></code>, and similar -elements.</p> - -<p>Declarations should reference the library components by their fully-qualified -package names, where appropriate. </p> - -<p>For example, the -<a href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> -example application declares the library Activity <code>GameActivity</code> -like this: </p> - -<pre><manifest> - ... - <application> - ... - <activity android:name="com.example.android.tictactoe.library.GameActivity" /> - ... - </application> -</manifest></pre> - -<p>For more information about the manifest file, see the documentation for <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> - -<h3 id="depAppBuild">Building a dependent application</h3> - -<p>To build an application project that depends on one or more library projects, -you can use the standard Ant build commands and compile modes, as described in -<a href="#Building">Building Your Application</a>, earlier in this document. The -tools compile and merge all libraries referenced by the application as part -of compiling the dependent application project. No additional commands or steps -are necessary. </p> - -<h3 id="considerations">Development considerations</h3> - -<p>As you develop your library project and dependent applications, keep the -points listed below in mind.</p> - -<p><strong>Resource conflicts</strong></p> - -<p>Since the tools merge the resources of a library project with those of a -dependent application project, a given resource ID might be defined in both -projects. In this case, the tools select the resource from the application, or -the library with highest priority, and discard the other resource. As you -develop your applications, be aware that common resource IDs are likely to be -defined in more than one project and will be merged, with the resource from the -application or highest-priority library taking precedence.</p> - -<p><strong>Using prefixes to avoid resource conflicts</strong></p> - -<p>To avoid resource conflicts for common resource IDs, consider using a prefix -or other consistent naming scheme that is unique to the project (or is unique -across all projects). </p> - -<p><strong>No export of library project to JAR</strong></p> - -<p>A library cannot be distributed as a binary file (such as a jar file). This -is because the library project is compiled by the main project to use the -correct resource IDs.</p> - -<p><strong>A library project can include a JAR library</strong></p> - -<p>You can develop a library project that itself includes a JAR library. When -you build the dependent application project, the tools automatically locate and -include the library in the application <code>.apk</code>. </p> - -<p><strong>A library project can depend on an external JAR library</strong></p> - -<p>You can develop a library project that depends on an external library (for -example, the Maps external library). In this case, the dependent application -must build against a target that includes the external library (for example, the -Google APIs Add-On). Note also that both the library project and the dependent -application must declare the external library their manifest files, in a <a -href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a> -element. </p> - -<p><strong>Library project cannot include raw assets</strong></p> - -<p>The tools do not support the use of raw asset files in a library project. -Any asset resources used by an application must be stored in the -<code>assets/</code> directory of the application project -itself.</p> - -<p><strong>Targeting different Android platform versions in library project and -application project</strong></p> - -<p>A library is compiled as part of the dependent application project, so the -API used in the library project must be compatible with the version of the -Android library used to compile the application project. In general, the library -project should use an <a href="{@docRoot}guide/appendix/api-levels.html">API level</a> -that is the same as — or lower than — that used by the application. -If the library project uses an API level that is higher than that of the -application, the application project will fail to compile. It is perfectly -acceptable to have a library that uses the Android 1.5 API (API level 3) and -that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) -project, for instance.</p> - -<p><strong>No restriction on library package name</strong></p> - -<p>There is no requirement for the package name of a library to be the same as -that of applications that use it.</p> - -<p><strong>Multiple R classes in gen/ folder of application project</strong></p> - -<p>When you build the dependent application project, the code of any libraries -is compiled and merged to the application project. Each library has its own -<code>R</code> class, named according to the library's package name. The -<code>R</code> class generated from the resources of the main project and of the -library is created in all the packages that are needed including the main -project’s package and the libraries’ packages.</p> - -<p><strong>Testing a library project</strong></p> - -<p>There are two recommended ways of setting up testing on code and resources in -a library project: </p> - -<ul> -<li>You can set up a <a -href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a> -that instruments an application project that depends on the library project. You -can then add tests to the project for library-specific features.</li> -<li>You can set up a set up a standard application project that depends on the -library and put the instrumentation in that project. This lets you create a -self-contained project that contains both the tests/instrumentations and the -code to test.</li> -</ul> - -<p><strong>Library project storage location</strong></p> - -<p>There are no specific requirements on where you should store a library -project, relative to a dependent application project, as long as the application -project can reference the library project by a relative link. You can place the -library project What is important is that the main project can reference the -library project through a relative link.</p> - -<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> -<ol> - <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 - 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> 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/aapt.html b/docs/html/guide/developing/tools/aapt.html new file mode 100644 index 0000000..e66a201 --- /dev/null +++ b/docs/html/guide/developing/tools/aapt.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/building/index.html#detailed-build"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/building/index.html#detailed-build">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/aapt.jd b/docs/html/guide/developing/tools/aapt.jd deleted file mode 100644 index 40a209d..0000000 --- a/docs/html/guide/developing/tools/aapt.jd +++ /dev/null @@ -1,20 +0,0 @@ -page.title=Using aapt -@jd:body - -<p><strong>aapt</strong> stands for Android Asset Packaging Tool and is included in the <code>tools/</code> directory of the SDK. This tool allows you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary assets. -</p> -<p> -Though you probably won't often use <strong>aapt</strong> directly, build scripts and IDE plugins can utilize this tool to package the apk file that constitutes an Android application. -</p> -<p> -For more usage details, open a terminal, go to the <code>tools/</code> directory, and run the command: -</p> -<ul> - <li><p>Linux or Mac OS X:</p> - <pre>./aapt</pre> - </li> - <li><p>Windows:</p> - <pre>aapt.exe</pre> - </li> -</ul> - diff --git a/docs/html/guide/developing/tools/avd.html b/docs/html/guide/developing/tools/avd.html new file mode 100644 index 0000000..c8455db --- /dev/null +++ b/docs/html/guide/developing/tools/avd.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/devices/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/devices/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd deleted file mode 100644 index ca197cf..0000000 --- a/docs/html/guide/developing/tools/avd.jd +++ /dev/null @@ -1,447 +0,0 @@ -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> - <li>You can launch a graphical Android AVD Manager either through Eclipse or -through the <code>android</code> tool. The <code>android</code> tool also offers -a command-line interface for creating and managing AVDs.</li> </ul> - <h2>In this document</h2> - <ol> - <li><a href="#creating">Creating an AVD</a> - <ol> - <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>The easiest way to create an AVD is to use the graphical AVD Manager, which -you can launch from Eclipse or from the command line using the -<code>android</code> tool. The <code>android</code> tool is provided in the -<code>tools/</code> directory of the Android SDK. When you run the -<code>android</code> tool without options, it launches the graphical AVD -Manager.</p> - -<p>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"> -<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>The easiest way to create an AVD is to use the graphical AVD Manager, but the -<code>android</code> tool also offers a <a href="#options">command line option</a>.</p> -<p>To create an AVD:</p> -<ol> - <li>In Eclipse, choose <strong>Window > Android SDK and AVD Manager</strong>. </li> - <p>Alternatively, you can launch the graphical AVD Manager by running the -<code>android</code> tool with no options.</p> - <li>Select <strong>Virtual Devices</strong> in the left panel.</li> - - <li>Click <strong>New</strong>. </li> - -<p>The <strong>Create New AVD</strong> dialog appears.</p> <a -href="{@docRoot}images/developing/avd-dialog.png"><img -src="{@docRoot}images/developing/avd-dialog.png" alt="AVD -Dialog" /></a> - - <li>Type the name of the AVD, such as "my_avd".</li> - <li>Choose a target. </li> -<p>The target is the system image that you want to run on the emulator, -from the set of platforms that are installed in your SDK environment. You can -choose a version of the standard Android platform or an SDK add-on. For more -information about how to add platforms to your SDK, see <a -href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. </p> - <li>Optionally specify any additional settings: </li> - <dl> - <dt><em>SD Card</em></dt> <dd>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.</dd> </dl> -<dt><em>Skin</em></dt> - <dd>The skin to use for this AVD, identified by name or dimensions.</dd> -<dt><em>Hardware</em></dt> - <dd>The hardware emulation options for the device. For a list of the options, see -<a href="#hardwareopts">Setting hardware emulation options</a>.</dd> - </dl> - <li>Click <strong>Create AVD</strong>.</li> -</ol> - -<h3 id="hardwareopts">Setting hardware emulation options</h3> - -<p>When you create a new AVD that uses a standard Android system image ("Type: -platform"), the AVD Manager - lets you set hardware emulation -options for your 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 <code>config.ini</code> 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> - -<tr> -<td>Abstracted LCD density</td> -<td>Sets the generalized density characteristic used by the AVD's screen. Most -skins come with a value (which you can modify), but if a skin doesn't provide -its own value, the default is 160. </td> -<td>hw.lcd.density </td> -</tr> - -<tr> -<td>Max VM application heap size</td> -<td>The maximum heap size a Dalvik application might allocate before being -killed by the system. Value is in megabytes. Most skins come with a value (which -you can modify), but if a skin doesn't provide its own value, the default is -16.</td> -<td>vm.heapSize</td> -</tr> - -</table> - -<h3 id="location">Default location of the AVD files</h3> - -<p>When you create an AVD, the AVD Manager 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 AVD Manager also creates a <code><AVD name>.ini</code> file for the -AVD at the root of the <code>.android/avd</code> directory on your computer. The file -specifies the location of the AVD directory and always remains at the root the -.android directory.</p> - -<p>By default, the AVD Manager 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 (command line tool only): </p> - -<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre> - -<p>If the <code>.android</code> 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 <code>.ini</code> file remains in the <code>.android</code> 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 you rename or move the root directory of a platform (or add-on), an AVD configured to use that platform will no longer be able to load the system image properly. To fix the AVD, use the <strong>Repair...</strong> button in the AVD Manager. From the command line, you can also 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 delete an AVD in the AVD Manager by selecting the -AVD and clicking <strong>Delete</strong>.</p> - -<p>Alternatively, you can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p> - -<pre>android delete avd -n <name> </pre> - -<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the -specified name deletes the AVD's directory and files. </p> - - -<h2 id="options">Command-line options</h2> - -<p>You can use the <code>android</code> tool to create and manage AVDs.</p> - -<p>The command line for creating an AVD has the following syntax:</p> - -<pre> -android create avd -n <name> -t <targetID> [-<option> <value>] ... -</pre> - -<p>Here's an example that creates an AVD with the name "my_android2.2" and target ID "3":</p> - -<pre> -android create avd -n my_android2.2 -t 3 -</pre> - -<p>The table below lists the command-line options you can use with the -<code>android</code> 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 <code>android</code> tool will not create the new AVD or overwrite - the existing AVD. If you specify the <code>-f</code> option, however, the - <code>android</code> 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 <code>android</code> tool scans for a matching skin by name or dimension in the -<code>skins/</code> directory of the target referenced in the <code>-t -<targetID></code> argument. 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/ddms.html b/docs/html/guide/developing/tools/ddms.html new file mode 100644 index 0000000..052ccc9 --- /dev/null +++ b/docs/html/guide/developing/tools/ddms.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/debugging/ddms.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/debugging/ddms.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/ddms.jd b/docs/html/guide/developing/tools/ddms.jd deleted file mode 100644 index f55940d..0000000 --- a/docs/html/guide/developing/tools/ddms.jd +++ /dev/null @@ -1,251 +0,0 @@ -page.title=Using the Dalvik Debug Monitor -@jd:body - -<p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), - which provides port-forwarding services, screen capture on the device, thread - and heap information on the device, logcat, process, and radio state information, - incoming call and SMS spoofing, location data spoofing, and more. This page - provides a modest discussion of DDMS features; it is not an exhaustive exploration of - all the features and capabilities.</p> - -<p>DDMS ships in the <code>tools/</code> directory of the SDK. - Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code> - on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are - connected and running simultaneously, DDMS defaults to the emulator.</p> - -<h2 id="how-ddms-works">How DDMS works</h2> -<p>DDMS acts as a middleman to connect the IDE to the applications running on -the device. On Android, every application runs in its own process, -each of which hosts its own virtual machine (VM). And each process -listens for a debugger on a different port.</p> - -<p>When it starts, DDMS connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> and -starts a device monitoring service between the two, which will notify DDMS when a device is -connected or disconnected. When a device is connected, a VM monitoring service is created -between adb and DDMS, which will notify DDMS when a VM on the device is started -or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb, -and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device. -DDMS can now talk to the VM using a custom wire protocol.</p> - -<p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p> - -<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p> - -<p>For more information on port-forwarding with DDMS, -read <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">Configuring your IDE to attach -to port 8700 for debugging</a>.</p> - -<p class="note"><strong>Tip:</strong> -You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>. -Preferences are saved to "$HOME/.ddmsrc". </p> - -<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/> -Debugging an application in the Dalvik VM should work the same as it does -in other VMs. However, when single-stepping out of synchronized code, the "current line" -cursor may jump to the last line in the method for one step.</p> - - -<h2 id="left-pane">Left Pane</h2> -<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of - all the VMs currently running within each. - VMs are identified by the package name of the application it hosts.</p> -<p>Use this list to find and attach to the VM - running the activity(ies) that you want to debug. Next to each VM in the - list is a "debugger pass-through" port (in the right-most column). - If you connect your debugger to one of the the ports listed, you - will be connected to the corresponding VM on the device. However, when using - DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the - currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.) - This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p> -<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()} - (or you select this option in the <a href="{@docRoot}guide/developing/debug-tasks.html#additionaldebugging">developer - options</a>), a red icon will be shown next to the client name, while it waits for the - debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p> -<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a -connection between the debugger and the VM because it was unable to open the VM's local port. -If you see this for all VMs on the device, it is likely because you have another instance of -DDMS running (this includes the Eclipse plugin).</p> -<p>If you see a question mark in place of an application package, this means that, -once DDMS received the application pid from adb, it -somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p> - - -<h2 id="right-pane">Right pane</h2> -<p>On the right side, the Debug Monitor provides tabs that display useful information -and some pretty cool tools.</p> - -<h3 id="info">Info</h3> -<p>This view shows some general information about the selected VM, including the process - ID, package name, and VM version.</p> - -<h3 id="threads">Threads</h3> -<p> The threads view has a list of threads running in the process of the target VM. - To reduce the amount - of data sent over the wire, the thread updates are only sent when explicitly - enabled by toggling the "threads" button - in the toolbar. This toggle is maintained per VM. This tab includes the following - information: </p> -<ul> - <li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are - odd numbers starting from 3. </li> - <li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process, - this will match the process ID. </li> - <li> <strong>Status</strong> - the VM thread status. Daemon threads are - shown with an asterisk (*). This will be one of the following: - <ul> - <li> <em>running</em> - executing application code </li> - <li> <em>sleeping</em> - called Thread.sleep() </li> - <li> <em>monitor</em> - waiting to acquire a monitor lock </li> - <li> <em>wait</em> - in Object.wait() </li> - <li> <em>native</em> - executing native code </li> - <li> <em>vmwait</em> - waiting on a VM resource </li> - <li> <em>zombie</em> - thread is in the process of dying </li> - <li> <em>init</em> - thread is initializing (you shouldn't see this) </li> - <li> <em>starting</em> - thread is about to start (you shouldn't see - this either) </li> - </ul> - </li> - <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually - 10ms). </li> - <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually - 10ms). </li> - <li> <strong>Name</strong> - the name of the thread</li> -</ul> -<p> "ID" and "Name" are set when the thread is started. The remaining - fields are updated periodically (default is every 4 seconds). </p> - -<h3 id="vm-heap">VM Heap</h3> -<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected, -the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button, -located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong> -to perform garbage collection and update the heap stats.</p> - - -<h3 id="allocation-tracker">Allocation Tracker</h3> -<p>In this view, you can track the memory allocation of each virtual machine. -With a VM selected in the left pane, click <strong>Start Tracking</strong>, then -<strong>Get Allocations</strong> to view all allocations since tracking started. -The table below will be filled with all the relevant -data. Click it again to refresh the list.</p> - - -<h3 id="emulator-control">Emulator Control</h3> -<p>With these controls, you can simulate special device states and activities. -Features include:</p> -<ul> -<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans - (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency - (GPRS, EDGE, UTMS, etc.).</li> -<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li> -<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform - location-aware operations like GPS mapping. - -<p>To use the Location Controls, launch your application in the Android emulator and open DDMS. -Click the Emulator Controls tab and scroll down to Location Controls. -From here, you can:</p> -<ul class="listhead"> - <li>Manually send individual longitude/latitude coordinates to the device. - <p>Click <strong>Manual</strong>, - select the coordinate format, fill in the fields and click <strong>Send</strong>. - </p> - </li> - <li>Use a GPX file describing a route for playback to the device. - <p>Click <strong>GPX</strong> and load the file. Once loaded, - click the play button to playback the route for your location-aware application.</p> - <p>When performing playback from GPX, you can adjust the speed of - playback from the DDMS panel and control playback with the pause and skip buttons. - DDMS will parse both the waypoints (<code><wpt></code>, in the first table), - and the tracks (<code><trk></code>, - in the second table, with support for multiple segments, <code><trkseg></code>, - although they are simply - concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply - sends its coordinate to the device, while selecting a track lets you play it.</p> - </li> - <li>Use a KML file describing individual placemarks for sequenced playback to the device. - <p>Click <strong>KML</strong> and load the file. Once loaded, - click the play button to send the coordinates to your location-aware application.</p> - <p>When using a KML file, it is parsed for a <code><coordinates></code> - element. The value of which should be a single - set of longitude, latitude and altitude figures. For example:</p> - <pre><coordinates>-122.084143,37.421972,4</coordinates></pre> - <p>In your file, you may include multiple <code><Placemark></code> elements, each containing - a <code><coordinates></code> element. When you do so, the collection of placemarks will - be added as tracks. DDMS will send one placemark per second to the device.</p> - <p>One way to generate a suitable KML file is to find a location in Google Earth. - Right-click the location entry that appears on the left and select "Save place as..." - with the save format set to Kml.</p> -<p class="note"><strong>Note:</strong> DDMS does not support routes created with the -<code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods. - There is also currently no support for the <code><TimeStamp></code> node inside - the <code><Placemark></code>. - Future releases may support timed placement and routes within a single coordinate element.</p> - </li> - </ul> - <p>For <em>additional</em> methods of setting up mocks of location-based data, see the - <a href="{@docRoot}guide/topics/location/index.html">Location</a> topic.</p> - </li> -</ul> - - -<!-- <h4>Event Log</h4> --> - - -<h2 id="file-explorer">File Explorer</h2> -<p>With the File Explorer, you can view the device file system and perform basic management, -like pushing and pulling files. This circumvents using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> -<code>push</code> and <code>pull</code> commands, with a GUI experience.</p> -<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the -File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them. -To copy files from the device, select the file and click the <strong>Pull File from Device</strong> -button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p> -<p>If you're interested in using an SD card image on the emulator, you're still required to use -the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup. -For example, from the <code>/tools</code> directory, execute:</p> -<pre> -<b>$</b> mksdcard 1024M ./img -<b>$</b> emulator -sdcard ./img -</pre> -<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the -sdcard directory. However, your files may not appear automatically. For example, if you add an -MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting -the emulator from command line, be sure to mount the sdcard again.)</p> -<p>For more information on creating an SD card image, see the -<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">Other Tools</a> document.</p> - -<h2 id="screen-capture">Screen Capture</h2> -<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> - > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S. - Be sure to select a device first.</p> - -<h2 id="exploring-processes">Exploring Processes</h2> -<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> - > <strong>Show process status</strong>... in the menu bar.</p> - -<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> -<p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p> - -<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> -<ul> - <li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> > - <strong>Run logcat...</strong> in the menu bar.</li> - <li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device - state...</strong> in the menu bar. </li> -</ul> - -<h2 id="examine-radio-state">Examine Radio State</h2> -<p>By default, radio state is not output during a standard logcat (it is a lot of - information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio - state...</strong> or run logcat as described in <a href="{@docRoot}guide/developing/debug-tasks.html#logradio">Logging - Radio Information</a>. </p> - -<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> -<p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt -VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p> - -<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> -<p>DDMS has the following known limitations:</p> -<ul> - <li>If you connect and disconnect a debugger, ddms drops and reconnects the - client so the VM realizes that the debugger has gone away. This will be fixed - eventually. </li> -</ul> diff --git a/docs/html/guide/developing/tools/hierarchy-viewer.jd b/docs/html/guide/developing/tools/hierarchy-viewer.jd index 431008c..ce660fc 100644 --- a/docs/html/guide/developing/tools/hierarchy-viewer.jd +++ b/docs/html/guide/developing/tools/hierarchy-viewer.jd @@ -1,98 +1,16 @@ page.title=Hierarchy Viewer @jd:body -<p>The Hierarchy Viewer application allows you to debug and optimize your user +<p>Hierarchy Viewer allows you to debug and optimize your user interface. It provides a visual representation of the layout's View hierarchy (the Layout View) and a magnified inspector of the display (the Pixel Perfect View). </p> -<p>To get the Hierarchy Viewer started:</p> -<ol> - <li>Connect your device or launch an emulator.</li> - <li>From a terminal, launch <code>hierarchyviewer</code> from your SDK - <code>/tools</code> directory. - </li> - <li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is - selected, a list of currently active <strong>Windows</strong> is displayed - on the right. The <em><Focused Window></em> is the window currently in - the foreground, and also the default window loaded if you do not select another. - </li> - <li>Select the window that you'd like to inspect and click - <strong>Load View Hierarchy</strong>. The Layout View will be loaded. - You can then load the Pixel Perfect View by clicking the second - icon at the bottom-left of the window. - </li> +<p>To start Hierarchy Viewer, enter the following command from the SDK <code>tools/</code> directory:</p> + <pre>hierarchyviewer</pre> </ol> -<p>If you've navigated to a different window on the device, press <strong>Refresh Windows</strong> -to refresh the list of available windows on the right.</p> - -<h2>Layout View</h2> -<p>The Layout View offers a look at the View layout and properties. It has three views:</p> -<ul> - <li>Tree View: a hierarchy diagram of the Views, on the left.</li> - <li>Properties View: a list of the selected View's properties, on the top-right.</li> - <li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li> -</ul> -<br/> -<img src="{@docRoot}images/hierarchyviewer-layout.png" alt="" height="509" width="700" /> - -<p>Select a node in the Tree View to display the properties of that element in -the Properties View. When a node is selected, the Wire-frame View -also indicates the bounds of the element with a red rectangle. -Double click a node in the tree (or select it, and click <strong>Display -View</strong>) to open a new window with a rendering of that element.</p> - -<p>The Layout View includes a couple other helpful features for debugging your layout: -<strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the -respective View calls, {@link android.view.View#invalidate()} and {@link android.view.View#requestLayout()}, -on the View element currently selected in the tree. Calling these methods on any View can -be very useful when simultaneously running a debugger on your application.</p> - -<p>The Tree View can be resized by adjusting the zoom slider, below -the diagram. The number of View elements in the window is also given here. You -should look for ways to minimize the number of Views. The fewer View elements there -are in a window, the faster it will perform.</p> - -<p>If you interact with the device and change the focused View, the diagram will not automatically refresh. -You must reload the Layout View by clicking <strong>Load View Hierarchy</strong>. - - -<h2>Pixel Perfect View</h2> -<p>The Pixel Perfect View provides a magnified look at the current device window. It has three views:</p> -<ul> - <li>Explorer View: shows the View hierarchy as a list, on the left.</li> - <li>Normal View: a normal view of the device window, in the middle.</li> - <li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li> -</ul> -<br/> -<img src="{@docRoot}images/hierarchyviewer-pixelperfect.png" alt="" height="509" width="700" /> - -<p>Click on an element in the Explorer View and a "layout box" will be drawn in the -Normal View to indicate the layout position of that element. The layout box uses multiple rectangles, to indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle indicates -the normal bounds of the element (the height and width). The inner white or black rectangle indicates -the content bounds, when padding is present. A black or white rectangle outside the normal purple/green -rectangle indicates any present margins. -(There are two colors for each rectangle, in order to provide the best contrast -based on the colors currently in the background.)</p> - -<p>A very handy feature for designing your UI is the ability to overlay an image in the Normal and Loupe -Views. For example, you might have a mock-up image of how you'd like to layout your interface. -By selecting <strong>Load...</strong> from the controls in the Normal View, you can choose the -image from your computer and it will be placed atop the preview. Your chosen image will anchor at the bottom left corner of the screen. You can then adjust the opacity of the overlay and begin fine-tuning your layout to match the mock-up.</p> - -<p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the -Explorer View does not. If you navigate away and focus on a different View, then you should refresh the -Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even true -when you're working in a window that holds multiple Views that are not always visible. If you do not, -although the previews will refresh, clicking a View in the Explorer will not provide the proper layout box -in the Normal View, because the hierarchy believes you are still focused on the prior View.</p> - -<p>Optional controls include:</p> -<ul> - <li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li> - <li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their display.</li> - <li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li> -</ul> - +<p>For more information on how to use Hierarchy Viewer, see +<a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Debugging and Profiling UIs</a> +</p> diff --git a/docs/html/guide/developing/tools/othertools.html b/docs/html/guide/developing/tools/othertools.html new file mode 100644 index 0000000..a074f33 --- /dev/null +++ b/docs/html/guide/developing/tools/othertools.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/tools/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/tools/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/othertools.jd b/docs/html/guide/developing/tools/othertools.jd deleted file mode 100644 index 00f0b8d..0000000 --- a/docs/html/guide/developing/tools/othertools.jd +++ /dev/null @@ -1,95 +0,0 @@ -page.title=Other Tools -@jd:body - -<p>The sections below describe other tools that you can use when building -Android applications. </p> - -<p>All of the tools are included in the Android SDK and are accessible from the -<code><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> -</dl> - -<a name="activitycreator"></a> -<h2 id="android">android</h2> - -<p>{@code android} is an important development tool that lets you:</p> - -<ul> - <li>Create, delete, and view Android Virtual Devices (AVDs). See - <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</li> - <li>Create and update Android projects. See - <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li> - <li>Update your Android SDK with new platforms, add-ons, and documentation. See - <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li> -</ul> - -<p>If you develop in Eclipse with the ADT plugin, you can perform -these tasks directly from the IDE. To create -Android projects and AVDs from Eclipse, see <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing -In Eclipse</a>. To update your SDK from Eclipse, see -<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. -</p> - - -<a name="mksdcard"></a> - -<h2>mksdcard</h2> - -<p>The mksdcard tool lets you quickly create a FAT32 disk image that you can -load in the emulator, to simulate the presence of an SD card in the device. -Here is the usage for mksdcard:</p> - -<pre>mksdcard [-l label] <size>[K|M] <file></pre> - -<p>The table below lists the available options/arguments</p> - -<table> -<tr> - <th>Argument</th> - <th>Description</th> -</tr> - -<tr> - <td><code>-l</code></td> - <td>A volume label for the disk image to create. </td> -</tr> - -<tr> - <td><code>size</code></td> - <td>An integer that specifies the size (in bytes) of disk image to create. -You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to -<size>. For example, <code>1048576K</code>, <code>1024M</code>.</td> -</tr> - -<tr> - <td><code>file</code></td> - <td>The path/filename of the disk image to create. </td> -</tr> - -</table> - -<p>Once you have created the disk image file, you can load it in the emulator at -startup using the emulator's -sdcard option. For more information, see -<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p> - -<pre>emulator -sdcard <file></pre> - -<a name="dx"></a> - -<h2>dx</h2> - -<p>The dx tool lets you generate Android bytecode from .class files. The tool -converts target files and/or directories to Dalvik executable format (.dex) files, -so that they can run in the Android environment. It can also dump the class files -in a human-readable format and run a target unit test. You can get the usage and -options for this tool by using <code>dx --help</code>.</p> - - - - diff --git a/docs/html/guide/developing/tools/traceview.jd b/docs/html/guide/developing/tools/traceview.jd index 95ae823..422fe00 100644 --- a/docs/html/guide/developing/tools/traceview.jd +++ b/docs/html/guide/developing/tools/traceview.jd @@ -1,319 +1,14 @@ -page.title=Traceview: A Graphical Log Viewer +page.title=Traceview @jd:body -<div id="qv-wrapper"> -<div id="qv"> +<p>Traceview is a graphical viewer for execution logs saved by your application. +Traceview can help you debug your application and profile its performance.</p> - <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> +<p>To start Traceview, enter the following command from the SDK <code>tools/</code> directory:</p> + <pre>traceview</pre> </ol> -</div> -</div> -<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> - -<h2>Creating Trace Files</h2> - -<p>To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you include the {@link android.os.Debug} - class in your code and call its methods to start and stop logging of trace information - to disk. When your application quits, you can then use Traceview to examine the log files - for useful run-time information such - as method calls and run times. </p> -<p>To create the trace files, include the {@link android.os.Debug} class and call one - of the {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. - In the call, you specify a base name for the trace files that the system generates. - To stop tracing, call {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}. - These methods start and stop method tracing across the entire virtual machine. For - example, you could call startMethodTracing() in your activity's onCreate() - method, and call stopMethodTracing() in that activity's onDestroy() method.</p> - -<pre> - // start tracing to "/sdcard/calc.trace" - Debug.startMethodTracing("calc"); - // ... - // stop tracing - Debug.stopMethodTracing(); -</pre> - -<p>When your application calls startMethodTracing(), the system creates a -file called <code><trace-base-name>.trace</code>. This contains the -binary method trace data and a mapping table with thread and method names.</p> - -<p>The system then begins buffering the generated trace data, until your application calls - stopMethodTracing(), at which time it writes the buffered data to the - output file. - If the system reaches the maximum buffer size before stopMethodTracing() - is called, the system stops tracing and sends a notification - to the console. </p> - -<p>Interpreted code will run more slowly when profiling is enabled. Don't -try to generate absolute timings from the profiler results (i.e. "function -X takes 2.5 seconds to run"). The times are only -useful in relation to other profile output, so you can see if changes -have made the code faster or slower. </p> - -<p>When using the Android emulator, you must create an SD card image upon which -the trace files will be written. For example, from the <code>/tools</code> directory, you -can create an SD card image named "imgcd" and mount it when launching the emulator like so:</p> -<pre> -<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> - -<p>The format of the trace files is described <a href="#format">later - in this document</a>. </p> - -<a name="copyingfiles"></a> - -<h2>Copying Trace Files to a Host Machine</h2> -<p>After your application has run and the system has created your trace files <code><trace-base-name>.trace</code> - on a device or emulator, you must copy those files to your development computer. You can use <code>adb pull</code> to copy - the files. Here's an example that shows how to copy an example file, - calc.trace, from the default location on the emulator to the /tmp directory on -the emulator host machine:</p> -<pre>adb pull /sdcard/calc.trace /tmp</pre> - - -<a name="runningtraceview"></a> - -<h2>Viewing Trace Files in Traceview</h2> -<p>To run traceview and view the trace files, enter <code>traceview <trace-base-name></code>. - For example, to run Traceview on the example files copied in the previous section, - you would use: </p> - <pre>traceview /tmp/calc</pre> - - <p>Traceview loads the log files and displays their data in a window that has two panels:</p> - <ul> - <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread - and method started and stopped</li> - <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside a method</li> - </ul> - <p>The sections below provide addition information about the traceview output panes. </p> - -<a name="timelinepanel"></a> - -<h3>Timeline Panel </h3> -<p>The image below shows a close up of the timeline panel. Each thread’s - execution is shown in its own row, with time increasing to the right. Each method - is shown in another color (colors are reused in a round-robin fashion starting - with the methods that have the most inclusive time). The thin lines underneath - the first row show the extent (entry to exit) of all the calls to the selected - method. The method in this case is LoadListener.nativeFinished() and it was - selected in the profile view. </p> -<p><img src="/images/traceview_timeline.png" alt="Traceview timeline panel" width="893" height="284"></p> -<a name="profilepanel"></a> -<h3>Profile Panel</h3> -<p>The image below shows the profile pane. The profile pane shows a - summary of all the time spent in a method. The table shows - both the inclusive and exclusive times (as well as the percentage of the total - time). Exclusive time is the time spent in the method. Inclusive time is the - time spent in the method plus the time spent in any called functions. We refer - to calling methods as "parents" and called methods as "children." - When a method is selected (by clicking on it), it expands to show the parents - and children. Parents are shown with a purple background and children - with a yellow background. The last column in the table shows the number of calls - to this method plus the number of recursive calls. The last column shows the - number of calls out of the total number of calls made to that method. In this - view, we can see that there were 14 calls to LoadListener.nativeFinished(); looking - at the timeline panel shows that one of those calls took an unusually - long time.</p> -<p><img src="/images/traceview_profile.png" alt="Traceview profile panel." width="892" height="630"></p> - -<a name="format"></a> -<h2>Traceview File Format</h2> -<p>Tracing creates two distinct pieces of output: a <em>data</em> file, - which holds the trace data, and a <em>key</em> file, which - provides a mapping from binary identifiers to thread and method names. - The files are concatenated when tracing completes, into a - single <em>.trace</em> file. </p> - -<p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate -these files for you. If you have old key and data files that you'd still like to trace, you -can concatenate them yourself with <code>cat mytrace.key mytrace.data > mytrace.trace</code>.</p> - -<a name="datafileformat"></a> - -<h3>Data File Format</h3> -<p>The data file is binary, structured as - follows (all values are stored in little-endian order):</p> -<pre>* File format: -* header -* record 0 -* record 1 -* ... -* -* Header format: -* u4 magic 0x574f4c53 ('SLOW') -* u2 version -* u2 offset to data -* u8 start date/time in usec -* -* Record format: -* u1 thread ID -* u4 method ID | method action -* u4 time delta since start, in usec -</pre> -<p>The application is expected to parse all of the header fields, then seek - to "offset to data" from the start of the file. From there it just - reads - 9-byte records until EOF is reached.</p> -<p><em>u8 start date/time in usec</em> is the output from gettimeofday(). - It's mainly there so that you can tell if the output was generated yesterday - or three months ago.</p> -<p><em>method action</em> sits in the two least-significant bits of the - <em>method</em> word. The currently defined meanings are: </p> -<ul> - <li>0 - method entry </li> - <li>1 - method exit </li> - <li>2 - method "exited" when unrolled by exception handling </li> - <li>3 - (reserved)</li> -</ul> -<p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds. +<p>For more information on how to use Traceview, see +<a href="{@docRoot}guide/developing/debugging/debugging-tracing.html">Profiling with Traceview and dmtracedump</a> </p> -<a name="keyfileformat"></a> - -<h3>Key File Format</h3> -<p>The key file is a plain text file divided into three sections. Each - section starts with a keyword that begins with '*'. If you see a '*' at the start - of a line, you have found the start of a new section.</p> -<p>An example file might look like this:</p> -<pre>*version -1 -clock=global -*threads -1 main -6 JDWP Handler -5 Async GC -4 Reference Handler -3 Finalizer -2 Signal Handler -*methods -0x080f23f8 java/io/PrintStream write ([BII)V -0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V -0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V -0x080da620 java/lang/RuntimeException <init> ()V -[...] -0x080f630c android/os/Debug startMethodTracing ()V -0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V -*end</pre> -<dl> - <dt><em>version section</em></dt> - <dd>The first line is the file version number, currently - 1. - The second line, <code>clock=global</code>, indicates that we use a common - clock across all threads. A future version may use per-thread CPU time counters - that are independent for every thread.</dd> - <dt><em>threads section</em></dt> - <dd>One line per thread. Each line consists of two parts: the thread ID, followed - by a tab, followed by the thread name. There are few restrictions on what - a valid thread name is, so include everything to the end of the line.</dd> - <dt><em>methods section </em></dt> - <dd>One line per method entry or exit. A line consists of four pieces, - separated by tab marks: <em>method-ID</em> [TAB] <em>class-name</em> [TAB] - <em>method-name</em> [TAB] - <em>signature</em> . Only - the methods that were actually entered or exited are included in the list. - Note that all three identifiers are required to uniquely identify a - method.</dd> -</dl> -<p>Neither the threads nor methods sections are sorted.</p> - -<a name="knownissues"></a> -<h2>Traceview Known Issues</h2> -<dl> - <dt>Threads</dt> - <dd>Traceview logging does not handle threads well, resulting in these two problems: -<ol> - <li> If a thread exits during profiling, the thread name is not emitted; </li> - <li>The VM reuses thread IDs. If a thread stops and another starts, they - may get the same ID. </li> -</ol> -</dd> - -<a name="dmtracedump"></a> - -<h2>Using dmtracedump</h2> - -<p>The Android SDK includes dmtracedump, a tool that gives you an alternate way - of generating graphical call-stack diagrams from trace log files. The tool - uses the Graphviz Dot utility to create the graphical output, so you need to - install Graphviz before running dmtracedump.</p> - -<p>The dmtracedump tool generates the call stack data as a tree diagram, with each call - represented as a node. It shows call flow (from parent node to child nodes) using - arrows. The diagram below shows an example of dmtracedump output.</p> - -<img src="{@docRoot}images/tracedump.png" width="485" height="401" style="margin-top:1em;"/> - -<p style="margin-top:1em;">For each node, dmtracedump shows <code><ref> <em>callname</em> (<inc-ms>, - <exc-ms>,<numcalls>)</code>, where</p> - -<ul> - <li><code><ref></code> -- Call reference number, as used in trace logs</li> - <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, including all child methods)</li> - <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, not including any child methods)</li> - <li><code><numcalls></code> -- Number of calls</li> -</ul> - -<p>The usage for dmtracedump is: </p> - -<pre>dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name></pre> - -<p>The tool then loads trace log data from <trace-base-name>.data and <trace-base-name>.key. - The table below lists the options for dmtracedump.</p> - -<table> -<tr> - <th>Option</td> - <th>Description</th> -</tr> - - <tr> - <td><code>-d <trace-base-name> </code></td> - <td>Diff with this trace name</td> - </tr> - <tr> - <td><code>-g <outfile> </code></td> - <td>Generate output to <outfile></td> - </tr> - <tr> - <td><code>-h </code></td> - <td>Turn on HTML output</td> - </tr> - <tr> - <td><code>-o </code></td> - <td>Dump the trace file instead of profiling</td> - </tr> - <tr> - <td><code>-d <trace-base-name> </code></td> - <td>URL base to the location of the sortable javascript file</td> - </tr> - <tr> - <td><code>-t <percent> </code></td> - <td>Minimum threshold for including child nodes in the graph (child's inclusive - time as a percentage of parent inclusive time). If this option is not used, - the default threshold is 20%. </td> - </tr> - -</table> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 36ef81c..401337a 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -457,29 +457,40 @@ <li><a href="<?cs var:toroot ?>guide/developing/tools/dmtracedump.html">dmtracedump</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/draw9patch.html" >Draw 9-Patch</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/emulator.html">Emulator</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/hprof-conv.html">hprof-conv</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/layoutopt.html">layoutopt</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/logcat.html">logcat</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/mksdcard.html">mksdcard</a></li> + <li><a href="/guide/developing/tools/monkey.html">Monkey</a></li> - <li class="toggle-list"> - <div><a href="/guide/developing/tools/monkeyrunner_concepts.html"> - <span class="en">monkeyrunner</span> - </a></div> - <ul> - <li><a href="/guide/developing/tools/MonkeyDevice.html"> - <span class="en">MonkeyDevice</span> - </a></li> - <li><a href="/guide/developing/tools/MonkeyImage.html"> - <span class="en">MonkeyImage</span> - </a></li> - <li><a href="/guide/developing/tools/MonkeyRunner.html"> - <span class="en">MonkeyRunner</span> - </a></li> - </ul> - </li> - <li><a href="/guide/developing/tools/proguard.html">ProGuard</a></li> - <li><a href="/guide/developing/tools/adb.html#sqlite">sqlite3</a></li> + <li class="toggle-list"> + <div> + <a href="/guide/developing/tools/monkeyrunner_concepts.html"> + <span class="en">monkeyrunner</span> + </a> + </div> + <ul> + <li> + <a href="/guide/developing/tools/MonkeyDevice.html"> + <span class="en">MonkeyDevice</span> + </a> + </li> + <li> + <a href="/guide/developing/tools/MonkeyImage.html"> + <span class="en">MonkeyImage</span> + </a> + </li> + <li> + <a href="/guide/developing/tools/MonkeyRunner.html"> + <span class="en">MonkeyRunner</span> + </a> + </li> + </ul> + </li> + <li><a href="/guide/developing/tools/proguard.html">ProGuard</a></li> + <li><a href="/guide/developing/tools/adb.html#sqlite">sqlite3</a></li> + <li><a href="/guide/developing/tools/traceview.html">Traceview</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/zipalign.html">zipalign</a></li> </ul> </li> |