Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: update information about developing on a device. Remove details about ADP1 and revise intro. Add links to the device doc from installing guides. Revise the procedures for Running Your Application in both the Eclipse and Other IDE guides to specifically describe using a device and make both docs more consistent with each other." into froyo

Browse Source
This commit is contained in:
Scott Main
2010-04-27 18:35:53 -07:00
committed by Android (Google) Code Review
parent 996960dea8 01979991dc
commit eaa801e22a
4 changed files with 314 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
docs/html/guide/developing/device.jd
View File

@@ -5,12 +5,6 @@ page.title=Developing on a Device
<div id="qv"> <div id="qv">
<h2>In this document</h2> <h2>In this document</h2>
<ol> <ol>
<li><a href="#devices">Available Devices</a>
<ol>
<li><a href="#consumer">Consumer devices</a></li>
<li><a href="#dev-phone-1">Android Dev Phone 1</a></li>
</ol>
</li>
<li><a href="#setting-up">Setting up a Device for Development</a> <li><a href="#setting-up">Setting up a Device for Development</a>
<ol> <ol>
<li><a href="#VendorIds">USB Vendor IDs</a></li> <li><a href="#VendorIds">USB Vendor IDs</a></li>
@@ -21,101 +15,50 @@ page.title=Developing on a Device
<ol> <ol>
<li><a <li><a
href="{@docRoot}sdk/win-usb.html">USB Driver for Windows</a></li> href="{@docRoot}sdk/win-usb.html">USB Driver for Windows</a></li>
<li><a
href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse, with ADT</a></li>
<li><a
href="{@docRoot}guide/developing/other-ide.html">Developing in other IDEs</a></li>
</ol> </ol>
</div> </div>
</div> </div>
<p>When building mobile applications, it's vital to test them on real <p>When building a mobile application, it's important that you always test your application on a
devices prior to releasing them to users. This page covers what you need to know, real device before releasing it to users. This page describes how to set up your development
including the types of devices that you can use, and how to set one up for environment and Android-powered device for testing and debugging on the device.</p>
developing and debugging.</p>
<p>You can use any Android-powered device as an environment for running,
debugging, and testing your applications. The tools included in the SDK make it easy to install and
run your application on the device each time you compile. You can install your application on the
device <a
href="{@docRoot}guide/developing/eclipse-adt.html#RunningOnDevice">directly from
Eclipse</a> or <a href="{@docRoot}guide/developing/other-ide.html#RunningOnDevice">from the
command line</a>. If
you don't yet have a device, check with the service providers in your area to determine which
Android-powered devices are available.</p>
<h2 id="devices">Available Devices</h2> <p>If you want a SIM-unlocked phone, then you might consider either an Android Dev Phone or the
<p>Here are some options for obtaining devices capable of testing your applications.</p> Google Nexus One. Both are SIM-unlocked so that you can use them on any GSM network using a SIM
card. The Android Dev Phones also feature an unlocked bootloader so you can install custom system
images (great for developing and installing custom versions of the Android platform). To purchase a
<h3 id="consumer">Consumer devices</h3> Nexus One, visit <a href="http://www.google.com/phone">google.com/phone</a>. To purchase an Android
Dev Phone, see the <a href="http://market.android.com/publish">Android Market</a> site
<p>It's likely that one of your local mobile carriers offers an Android-powered device. (requires a developer account).</p>
Any Android-powered device (even one bought from your mobile carrier) is a perfectly good
device for running and testing your own Android applications.
You can write applications using the Android SDK and then install them
directly onto the device for testing.</p>
<p>Check with the service providers in your area to determine which Android-powered
devices are available.</p>
<p>Be aware that consumer devices are not designed to allow system image updates by the
user. If you're interested in manually updating the device with custom system images, then
you'll need a developer device such as the <a href="#dev-phone-1">Android Dev Phone 1</a>.</p>
<h3 id="dev-phone-1">Android Dev Phone 1</h3>
<div class="sidebox-wrapper">
<div class="sidebox">
<p>Selected specs for Android Dev Phone 1:</p>
<ul>
<li>Touch screen</li>
<li>Trackball</li>
<li>3.2 megapixel camera with autofocus</li>
<li>Wi-Fi</li>
<li>GPS-enabled</li>
<li>Bluetooth v2.0
<ul><li>Handsfree profile v1.5</li>
<li>Headset profile v1.0</li></ul></li>
<li>3G WCDMA (1700/2100 MHz)</li>
<li>Quad-band GSM (850/900/1800/1900 MHz)</li>
<li>QWERTY slider keyboard</li>
<li>Includes 1GB MicroSD card (can be replaced with up to 16GB card)</li>
</ul>
</div>
</div>
<p>The Android Dev Phone 1 is a SIM-unlocked and hardware-unlocked device that
is designed for advanced developers. The device ships with a system image that
is fully compatible with Android 1.0, so you can rely on it when developing your
applications. You can use any SIM in the device and can flash custom Android
builds that will work with the unlocked bootloader. Unlike the bootloader on
retail devices, the bootloader on the Android Dev Phone 1 does not enforce
signed system images. The Android Dev Phone 1 should also appeal to developers
who live in geographies where local mobile carriers do not currently offer Android-powered devices. </p>
<p>To purchase an Android Dev Phone 1 device, you must first register as an
Android developer on the Android Market site, if you haven't done so already.
Once you've logged into your developer account on Android Market, you can
purchase the device by following the link to "Development phones." To accommodate demand,
there is a limit of 1 device per developer account, for now.</p>
<p>The device currently costs $399 (USD) (including free shipping in the US),
and is available for purchase in 18 international markets, including the
US, UK, Germany, Japan, India, Canada, France, Taiwan, Spain, Australia,
Singapore, Switzerland, Netherlands, Austria, Sweden, Finland, Poland, and
Hungary. We will continue to expand this program into new geographies over
time. Check this page for updated information.</p>
<p>Android Dev Phone 1 devices are <em>not</em> intended for
non-developer end-users. Because the device can be configured with system
software not provided by or supported by Google or any other company, end-users
operate these devices at their own risk.</p>
<p>Note that your Android Dev Phone 1 will not receive automated
over-the-air (OTA) updates for the system image. System updates must be flashed manually.
See the HTC site for a guide to <a href="http://www.htc.com/www/support/android/adp.html">Flashing
your Android Dev Phone with a Factory System Image</a>.</p>
<p>For full device specs and more information about obtaining an Android Dev
Phone 1 device, see the <a href="http://market.android.com/publish">Android
Market</a> site.</p>
<p class="note"><strong>Note:</strong> When developing on a device, keep in mind that you should
still use the <a
href="{@docRoot}guide/developing/tools/emulator.html">Android emulator</a> to test your application
on configurations that are not equivalent to those of your real device. Although the emulator
does not allow you to test every device feature (such as the accelerometer), it does
allow you to verify that your application functions properly on different versions of the Android
platform, in different screen sizes and orientations, and more.</p>
<h2 id="setting-up">Setting up a Device for Development</h2> <h2 id="setting-up">Setting up a Device for Development</h2>
<p>With an Android-powered device, you can develop and debug your Android applications just as you <p>With an Android-powered device, you can develop and debug your Android applications just as you
would on the emulator. There are just a few things to do before you can start.</p> would on the emulator. Before you can start, there are just a few things to do:</p>
<ol> <ol>
<li>Declare your application as "debuggable" in your Android Manifest. <li>Declare your application as "debuggable" in your Android Manifest.
<p>In Eclipse, you can do this from the <b>Application</b> tab when viewing the Manifest <p>In Eclipse, you can do this from the <b>Application</b> tab when viewing the Manifest
@@ -159,37 +102,70 @@ href="#VendorIds">USB Vendor IDs</a>, below.
</ul> </ul>
</li> </li>
</ol> </ol>
<p>You can verify that your device is connected by executing <code>adb devices</code> from your
SDK tools/ directory. If connected, you'll see the device name listed as a "device."</p>
<p>If using Eclipse, select run or debug as usual. You will be presented
with a <b>Device Chooser</b> dialog that lists the available emulator(s) and connected device(s).
Select the device to install and run the application there.</p>
<p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb), <p>You can verify that your device is connected by executing <code>adb devices</code> from your
SDK {@code tools/} directory. If connected, you'll see the device name listed as a "device."</p>
<p>If using Eclipse, run or debug as usual. You will be presented
with a <b>Device Chooser</b> dialog that lists the available emulator(s) and connected device(s).
Select the device upon which you want to install and run the application.</p>
<p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb),
you can issue commands with the <code>-d</code> flag to target your you can issue commands with the <code>-d</code> flag to target your
connected device.</p> connected device.</p>
<h3 id="VendorIds">USB Vendor IDs</h3> <h3 id="VendorIds">USB Vendor IDs</h3>
<p>This table provides a reference to the vendor IDs needed in order to add <p>This table provides a reference to the vendor IDs needed in order to add
device support on Linux. The USB Vendor ID is the value given to the USB device support on Linux. The USB Vendor ID is the value given to the
<code>SYSFS{idVendor}</code> property in the rules file.</p> <code>SYSFS{idVendor}</code> property in the rules file, as described in step 3, above.</p>
<table> <table>
<tr> <tr>
<th>Manufacturer</th><th>USB Vendor ID</th></tr> <th>Manufacturer</th><th>USB Vendor ID</th></tr>
<tr> <tr>
<td>Acer</td><td>0502</td></tr> <td>Acer</td>
<td><code>0502</code></td></tr>
<tr> <tr>
<td>HTC</td><td>0bb4</td></tr> <td>Dell</td>
<td><code>413c</code></td></tr>
<tr> <tr>
<td>Huawei</td><td>12d1</td></tr> <td>Foxconn</td>
<td><code>0489</code></td></tr>
<tr> <tr>
<td>LG</td><td>1004</td></tr> <td>Garmin-Asus</td>
<td><code>091E</code></td></tr>
<tr> <tr>
<td>Motorola</td><td>22b8</td></tr> <td>HTC</td>
<td><code>0bb4</code></td></tr>
<tr> <tr>
<td>Samsung</td><td>04e8</td></tr> <td>Huawei</td>
<td><code>12d1</code></td></tr>
<tr> <tr>
<td>Sony Ericsson</td><td>0fce</td></tr> <td>Kyocera</td>
<td><code>0482</code></td></tr>
<tr>
<td>LG</td>
<td><code>1004</code></td></tr>
<tr>
<td>Motorola</td>
<td><code>22b8</code></td></tr>
<tr>
<td>Nvidia</td>
<td><code>0955</code></td></tr>
<tr>
<td>Pantech</td>
<td><code>10A9</code></td></tr>
<tr>
<td>Samsung</td>
<td><code>04e8</code></td></tr>
<tr>
<td>Sharp</td>
<td><code>04dd</code></td></tr>
<tr>
<td>Sony Ericsson</td>
<td><code>0fce</code></td></tr>
<tr>
<td>ZTE</td>
<td><code>19D2</code></td></tr>
</table> </table>

149
docs/html/guide/developing/eclipse-adt.jd
View File

@@ -6,10 +6,11 @@ page.title=Developing In Eclipse, with ADT
<h2>In this document</h2> <h2>In this document</h2>
<ol> <ol>
<li><a href="#CreatingAProject">Creating an Android Project</a></li> <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> <li><a href="#Running">Running Your Application</a>
<ol> <ol>
<li><a href="#CreatingAnAvd">Creating an AVD</a></li> <li><a href="#RunningOnEmulator">Running on the emulator</a></li>
<li><a href="#RunningAnApplication">Running an application</a></li> <li><a href="#RunningOnDevice">Running on a device</a></li>
</ol> </ol>
</li> </li>
<li><a href="#RunConfig">Creating a Custom Run Configuration</a></li> <li><a href="#RunConfig">Creating a Custom Run Configuration</a></li>
@@ -27,7 +28,8 @@ applications:</p>
<ul> <ul>
<li>It gives you access to other Android development tools from inside the Eclipse IDE. For <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 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> 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 <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> 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 automates and simplifies the process of building your Android application.</li>
@@ -70,7 +72,7 @@ Android project (or a project from existing code). To create a new project:</p>
The Build Target The Build Target
specifies which Android platform you'd like your application built against. 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 <p>Unless you know that you'll be using new APIs introduced in the latest SDK, you should
select a target with the lowest platform version possible, such as Android 1.1.</p> 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 <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 project at any time: Right-click the project in the Package Explorer, select
<strong>Properties</strong>, select <strong>Android</strong> and then check <strong>Properties</strong>, select <strong>Android</strong> and then check
@@ -89,7 +91,8 @@ Android project (or a project from existing code). To create a new project:</p>
the minimum API Level required to properly run your application. the minimum API Level required to properly run your application.
Entering this here automatically sets the <code>minSdkVersion</code> attribute in the Entering this here automatically sets the <code>minSdkVersion</code> attribute in the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a> <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a>
of your Android Manifest file. If you're unsure of the appropriate API Level to use, 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> copy the API Level listed for the Build Target you selected in the Target tab.</li>
</ul> </ul>
</li> </li>
@@ -133,87 +136,117 @@ folders and files in your new project:</p>
</dl> </dl>
<h2 id="Running">Running Your Application</h2> <h2 id="AVD">Creating an AVD</h2>
<p>Before you can run your application on the Android Emulator, <p>An Android Virtual Device (AVD) is a device configuration for the emulator that
you <strong>must</strong> create an Android Virtual Device (AVD). allows you to model real world devices. In order to run an instance of the emulator, you must create
An AVD is a configuration that specifies the Android platform to be used on the emulator. an AVD.</p>
You can read more in the <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual
Devices</a> document, but if you just want to get started, follow the simple guide below to
create an AVD.</p>
<p>If you will be running your applications only on actual device hardware, you do not <p>To create an AVD from Eclipse:</p>
need an AVD &mdash; see
<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> for information
on running your application.</p>
<h3 id="CreatingAnAvd">Creating an AVD</h3>
<p>With ADT 0.9.3 and above, the Android SDK and AVD Manager provides a simple graphical interface
for creating and managing AVDs. (If you're using ADT version 0.9.1 or older, you must
use the <code>android</code> tool to create your AVDs&mdash;read the AVD guide to
<a href="{@docRoot}guide/developing/tools/avd.html#creating">Creating an AVD</a>.)
<p>To create an AVD with the AVD Manager:</p>
<ol> <ol>
<li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and AVD Manager icon (a black device) <li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and
in the Eclipse toolbar.</p> AVD Manager icon in the Eclipse toolbar.</p>
</li> </li>
<li>In the Virtual Devices panel, you'll see a list of existing AVDs. Click <strong>New</strong> <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click
to create a new AVD.</li> <strong>New</strong> to create a new AVD.</li>
<li>Fill in the details for the AVD. <li>Fill in the details for the AVD.
<p>Give it a name, a platform target, an SD card image (optional), and <p>Give it a name, a platform target, an SD card size, and
a skin (HVGA is default).</p> 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>
<li>Click <strong>Create AVD</strong>.</li> <li>Click <strong>Create AVD</strong>.</li>
</ol> </ol>
<p>Your AVD is now ready and you can close the AVD Manager. <p>Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or
In the next section, you'll see how the AVD is used launch an emulator with the AVD by selecting a device and clicking <strong>Start</strong>.</p>
when launching your application on an emulator.</p>
<p>For more information about AVDs, read the <p>For more information about AVDs, read the
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>
documentation.</p> documentation.</p>
<h3 id="RunningYourApplication">Running your application</h3> <h2 id="Running">Running Your Application</h2>
<p class="note"><strong>Note:</strong> Before you can run your application, be sure that <div class="sidebox-wrapper">
you have created an AVD with a target that satisfies your application's Build Target. <div class="sidebox">
If an AVD cannot be found that meets the requirements of your Build Target, you will see <h2>Use the Emulator to Test Different Configurations</h2>
a console error telling you so and the launch will be aborted.</p> <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>To run (or debug) your application, select <strong>Run</strong> &gt; <strong>Run</strong> (or <p>Running your application from Eclipse will usually require just a couple clicks, whether you're
<strong>Run</strong> &gt; <strong>Debug</strong>) from the Eclipse main menu. The ADT plugin running it on the emulator or on an attached device. The information below describes how to get
will automatically create a default launch configuration for the project.</p> set up and run your application from Eclipse.</p>
<p>When you choose to run or debug your application, Eclipse will perform the following:</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> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <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> <ol>
<li>Compile the project (if there have been changes since the last build).</li> <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>Create a default launch configuration (if one does not already exist for the
<li>Install and start the application on an emulator or device (based on the Deployment Target project).</li>
defined by the run configuration). <li>Install and start the application on an emulator (or device), based on the Deployment
<p>By default, Android application run configurations use an "automatic target" mode for Target
selecting a device target. For information on how automatic target mode selects a defined by the run configuration.
deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual <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> target modes</a> below.</p>
</li> </li>
</ol> </ol>
<p>If debugging, the application will start in the "Waiting For Debugger" mode. Once the <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> 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. <p>To set or change the launch configuration used for your project, use the launch configuration
manager.
See <a href="#launchconfig">Creating a Launch Configuration</a> for information.</p> See <a href="#launchconfig">Creating a Launch 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> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <strong>Debug</strong>) from the Eclipse menu bar.</p>
<h2 id="RunConfig">Creating a Run Configuration</h2> <h2 id="RunConfig">Creating a Run Configuration</h2>
<p>The run configuration specifies the project to run, the Activity <p>The run configuration specifies the project to run, the Activity
to start, the emulator options to use, and so on. When you first run a project 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. as an <em>Android Application</em>, ADT will automatically create a run configuration.
The default run configuration will The default run configuration will
launch the default project Activity and use automatic target mode for device selection launch the default project Activity and use automatic target mode for device selection
@@ -240,7 +273,8 @@ for your Eclipse version:</p>
<ul> <ul>
<li>To create a new configuration: <li>To create a new configuration:
<ol> <ol>
<li>Select <strong>Android Application</strong> and click the <em>New launch configuration</em> <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 icon above the list (or, right-click <strong>Android Application</strong> and click
<strong>New</strong>).</li> <strong>New</strong>).</li>
<li>Enter a Name for your configuration.</li> <li>Enter a Name for your configuration.</li>
@@ -268,7 +302,8 @@ document.</p>
<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3> <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 <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> an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p>
<ol> <ol>
@@ -323,8 +358,8 @@ a guide to exporting and signing your application with the ADT's Export Wizard.<
information about packages and call class methods. You can also invoke arbitrary information about packages and call class methods. You can also invoke arbitrary
static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will
start dmTrace. </p> start dmTrace. </p>
<p>Open a code execution window, select <strong>Window</strong>&gt;<strong>Show <p>Open a code execution window, select <strong>Window</strong> &gt; <strong>Show
View</strong>&gt;<strong>Display</strong> from the main menu to open the View</strong> &gt; <strong>Display</strong> from the main menu to open the
Display window, a simple text editor. Type your expression, highlight 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 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 code. The code runs in the context of the selected thread, which must be

213
docs/html/guide/developing/other-ide.jd
View File

@@ -13,7 +13,13 @@ page.title=Developing In Other IDEs
<li><a href="#ReleaseMode">Building in release mode</a></li> <li><a href="#ReleaseMode">Building in release mode</a></li>
</ol> </ol>
</li> </li>
<li><a href="#Running">Running Your Application</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="#AttachingADebugger">Attaching a Debugger to Your Application</a></li> <li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li>
</ol> </ol>
@@ -97,15 +103,20 @@ android create project \
to an Android platform library (including any add-ons, such as Google APIs) that you would like to 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, build your project against. To see a list of available targets and their corresponding IDs,
execute: <code>android list targets</code>.</li> 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 <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> 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, <li><code>path</code> is the location of your project directory. If the directory does not exist,
it will be created for you.</li> 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 <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This
class file
will be created for you inside will be created for you inside
<code><em>&lt;path_to_your_project&gt;</em>/src/<em>&lt;your_package_namespace_path&gt;</em>/</code>.
<code><em>&lt;path_to_your_project&gt;</em>/src/<em>&lt;your_package_namespace_path&gt;</em>/</code>
.
This will also be used for your .apk filename unless you provide a the <code>name</code>.</li> 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 <li><code>package</code> is the package namespace for your project, following the same rules as
for
packages in the Java programming language.</li> packages in the Java programming language.</li>
</ul> </ul>
@@ -127,13 +138,16 @@ android create project \
<li><code>build.xml</code> - Build file for Ant.</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 <li><code>default.properties</code> - Properties for the build system. <em>Do not modify
this file</em>.</li> this file</em>.</li>
<li><code>build.properties</code> - Customizable properties for the build system. You can edit this <li><code>build.properties</code> - Customizable properties for the build system. You can edit
file to override default build settings used by Ant and provide a pointer to your keystore and key alias 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> 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 <li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class
you specified during project creation.</li> you specified during project creation.</li>
<li><code>bin/</code> - Output directory for the build script.</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>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>libs/</code> - Holds private libraries.</li>
<li><code>res/</code> - Holds project resources.</li> <li><code>res/</code> - Holds project resources.</li>
<li><code>src/</code> - Holds source code.</li> <li><code>src/</code> - Holds source code.</li>
@@ -167,13 +181,15 @@ as needed for the Android project.</p>
<p>To update an existing Android project, open a command-line <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> and navigate to the <code>tools/</code> directory of your SDK. Now run:</p>
<pre> <pre>
android update project --name <em>&lt;project_name&gt;</em> --target <em>&lt;target_ID&gt;</em> --path <em>path/to/your/project/</em> android update project --name <em>&lt;project_name&gt;</em> --target <em>&lt;target_ID&gt;</em>
--path <em>&lt;path_to_your_project&gt;</em>
</pre> </pre>
<ul> <ul>
<li><code>target</code> is the "build target" for your application. It corresponds to <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 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, like to build your project against. To see a list of available targets and their corresponding
IDs,
execute: <code>android list targets</code>.</li> execute: <code>android list targets</code>.</li>
<li><code>path</code> is the location of your project directory.</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&mdash;if you're not <li><code>name</code> is the name for the project. This is optional&mdash;if you're not
@@ -218,7 +234,8 @@ or device.</p>
<p>Whether you're building in debug mode or release mode, you <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 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 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 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). (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 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> sign it with your own private key, using Keytool and Jarsigner.</p>
@@ -239,7 +256,7 @@ 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 <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 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: 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 <code>set JAVA_HOME=c:\Progra~1\Java\&lt;jdkdir&gt;</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> install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>.</p>
@@ -322,8 +339,10 @@ for distribution.</p>
<p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that <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 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 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 may prefer to perform the application signing manually, via Jarsigner (or a similar tool). To
perform the signing procedure manually, <a href="#ManualReleaseMode">buid unsigned</a> and then continue 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> 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 <p>To specify your keystore and alias, open the project {@code build.properties} file (found in the
@@ -366,87 +385,125 @@ download the application and begin installation.
(On your device, be sure you have enabled <em>Settings > Applications > Unknown sources</em>.)</p> (On your device, be sure you have enabled <em>Settings > Applications > Unknown sources</em>.)</p>
<h2 id="Running">Running Your Application</h2> <h2 id="AVD">Creating an AVD</h2>
<p>Unless you'll be running your application on device hardware, <p>An Android Virtual Device (AVD) is a device configuration for the emulator that
you need to launch an emulator upon which you will install your application. allows you to model real world devices. In order to run an instance of the emulator, you must create
An instance of the Android emulator runs a specific Android platform with specific device configuration an AVD.</p>
settings. The platform and configuration is defined with an Android Virtual Device (AVD).
So before you can launch your emulator, you must define an AVD.</p>
<p>If you'll be running your application on device hardware, please read about <p>To create an AVD using the SDK tools:</p>
<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> instead.</p>
<ol> <ol>
<li><strong>Create an AVD</strong> <li>Navigate to your SDK's <code>tools/</code> directory and execute the {@code android}
<ol> tool with no arguments:
<li>Open a command-line and navigate to your SDK package's <pre>android</pre>
<code>tools/</code> directory.</li> <p>This will launch the SDK and AVD Manager GUI.</p>
<li>First, you need to select a "deployment target." To view available targets, execute: </li>
<pre>android list targets</pre> <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click
<p>This will output a list of available Android targets, such as:</p> <strong>New</strong>
<pre> to create a new AVD.</li>
id:1 <li>Fill in the details for the AVD.
Name: Android 1.1 <p>Give it a name, a platform target, an SD card size, and
Type: platform a skin (HVGA is default).</p>
API level: 2 <p class="note"><strong>Note:</strong> Be sure to define
Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P a target for your AVD that satisfies your application's build target (the AVD
id:2 platform target must have an API Level equal to or greater than the API Level that your
Name: Android 1.5 application compiles against).</p>
Type: platform </li>
API level: 3 <li>Click <strong>Create AVD</strong>.</li>
Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P </ol>
</pre>
<p>Find the target that matches the Android platform upon which you'd like <p>Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or
to run your application. Note the integer value of the <code>id</code> &mdash; launch an emulator with the AVD by clicking <strong>Start</strong>.</p>
you'll use this in the next step.</p>
</li> <p>For more information about AVDs, read the
<li>Create a new AVD using your selected deployment target: <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>
<pre>android create avd --name <em>&lt;your_avd_name&gt;</em> --target <em>&lt;target_ID&gt;</em></pre> documentation.</p>
<li>Next, you'll be asked whether you'd like to create a custom hardware profile.
If you respond "yes," you'll be presented with a series of prompts to define various aspects of the
device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise, <h2 id="Running">Running Your Application</h2>
press return to use all default values ("no" is the default).</li>
</li> <div class="sidebox-wrapper">
</ol> <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>
<li><strong>Launch an emulator</strong></li>
<p>From your SDK's <code>tools/</code> directory, launch an emulator
using an existing AVD (created above):
<pre>emulator -avd <em>&lt;your_avd_name&gt;</em></pre>
<p>An instance of the emulator will now launch, running the target and configuration
defined by your AVD.</p>
</li>
<li><strong>Install your application</strong> <li><strong>Install your application</strong>
<p>From your SDK's <code>tools/</code> directory, install the .apk on the emulator: <p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the
<pre>adb install <em>/path/to/your/application</em>.apk</pre> emulator:
<p>If there is more than one emulator running, you must specify the emulator upon which to install <pre>adb install <em>&lt;path_to_your_bin&gt;</em>.apk</pre>
the application, by its serial number, with the <code>-s</code> option. For example:</p> <p>Your APK file (signed with either a release or debug key) is in your project {@code bin/}
<pre>adb -s emulator-5554 install /my/project/path/myapp.apk</pre> directory after you <a href="#Building">build your application</a>.</p>
</li> <p>If there is more than one emulator running, you must specify the emulator upon which to
<li><strong>Open your application</strong> install the application, by its serial number, with the <code>-s</code> option. For example:</p>
<p>In the emulator, open the list of available applications to find <pre>adb -s emulator-5554 install <em>/path/to/your/app</em>.apk</pre>
and open your application.</p> <p>To see a list of available device serial numbers, execute {@code adb devices}.</p>
</li> </li>
</ol> </ol>
<p>If you don't see your application on the emulator. Try restarting the emulator <p>If you don't see your application on the emulator. Try closing the emulator and launching the
(with the same AVD). Sometimes when you install an Activity for 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 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 applications. This is because the package manager usually examines manifests
completely only on emulator startup.</p> completely only on emulator startup.</p>
<p class="note"><strong>Tip:</strong> If you have only one emulator running, <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. 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 Navigate to the root of your project directory and use Ant to compile the project
with <em>install mode</em>: with <em>install mode</em>:
<code>ant install</code>. This will build your application, sign it with the debug key, <code>ant install</code>. This will build your application, sign it with the debug key,
and install it on the currently running emulator. and install it on the currently running emulator.</p>
If there is more than one emulator currently running
when using the <code>install</code> command, it will fail &mdash; it can't select between the
multiple emulators.</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>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> <p>For more information on the tools used above, please see the following documents:</p>
<ul> <ul>

10
docs/html/sdk/installing.jd
View File

@@ -361,7 +361,7 @@ applications against, each in a separate directory. </td>
</tr> </tr>
<tr> <tr>
<td style="width:2em;border-bottom-color:white;"></td> <td style="width:2em;border-bottom-color:white;"></td>
<td colspan="2"><code>&lt;platform&gt;/</code></td> <td colspan="2"><code><em>&lt;platform&gt;</em>/</code></td>
<td>Platform version directory, for example "android-1.6". All platform version <td>Platform version directory, for example "android-1.6". All platform version
directories contain a similar set of files and subdirectory structure.</td> directories contain a similar set of files and subdirectory structure.</td>
</tr> </tr>
@@ -439,11 +439,11 @@ begin developing applications. Here are a few ways you can get started: </p>
<p><strong>Set up the Hello World application</strong></p> <p><strong>Set up the Hello World application</strong></p>
<ul> <ul>
<li>If you have just installed the SDK for the first time, <a <li>If you have just installed the SDK for the first time, go to the <a
href="{@docRoot}resources/tutorials/hello-world.html">go to the Hello href="{@docRoot}resources/tutorials/hello-world.html">Hello
World tutorial</a>. The tutorial takes you step-by-step through the process World tutorial</a>. The tutorial takes you step-by-step through the process
of setting up your first Android project, including setting up an Android of setting up your first Android project, including setting up an Android
Virtual Device (AVD) on which to run the application. Virtual Device (AVD) on which to run the application.
</li> </li>
</ul> </ul>
@@ -473,6 +473,8 @@ first step in getting started with Android development. </p>
href="{@docRoot}guide/developing/eclipse-adt.html">in Eclipse/ADT</a> or href="{@docRoot}guide/developing/eclipse-adt.html">in Eclipse/ADT</a> or
<a href="{@docRoot}guide/developing/other-ide.html">in other IDEs</a> <a href="{@docRoot}guide/developing/other-ide.html">in other IDEs</a>
</li> </li>
<li>Read <a href="{@docRoot}guide/developing/device.html">Developing on a Device</a> to set up an
Android-powered device to run and test your application.</li>
</ul> </ul>
<p><strong>Follow the Notepad tutorial</strong></p> <p><strong>Follow the Notepad tutorial</strong></p>