Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 01979991 authored by Scott Main's avatar Scott Main
Browse files

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.

Change-Id: Ica77533e78141db43eb3ed214309f571beff7353
parent 2e4b98dc

docs/html/guide/developing/device.jd

+82 −106
Original line number Diff line number Diff line
@@ -5,12 +5,6 @@ page.title=Developing on a Device 
<div id="qv">

  <h2>In this document</h2>

  <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>

      <ol>

        <li><a href="#VendorIds">USB Vendor IDs</a></li>
@@ -21,101 +15,50 @@ page.title=Developing on a Device 
  <ol>

    <li><a

    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>

</div>

</div>



<p>When building mobile applications, it's vital to test them on real

devices prior to releasing them to users. This page covers what you need to know, 

including the types of devices that you can use, and how to set one up for

developing and debugging.</p>





<h2 id="devices">Available Devices</h2>

<p>Here are some options for obtaining devices capable of testing your applications.</p>





<h3 id="consumer">Consumer devices</h3>



<p>It's likely that one of your local mobile carriers offers an Android-powered device.

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>When building a mobile application, it's important that you always test your application on a

real device before releasing it to users. This page describes how to set up your development

environment and Android-powered device for testing and debugging on the device.</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>



<p>If you want a SIM-unlocked phone, then you might consider either an Android Dev Phone or the

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

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

(requires a developer account).</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>



<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>

  <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
@@ -159,11 +102,13 @@ href="#VendorIds">USB Vendor IDs</a>, below. 
    </ul>

  </li>

</ol>



<p>You can verify that your device is connected by executing <code>adb devices</code> from your 

SDK tools/ directory. If connected, you'll see the device name listed as a "device."</p>

<p>If using Eclipse, select run or debug as usual. You will be presented

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 to install and run the application there.</p>

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
@@ -172,24 +117,55 @@ connected device.</p> 


<h3 id="VendorIds">USB Vendor IDs</h3>

<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

<code>SYSFS{idVendor}</code> property in the rules file.</p>

USB device support on Linux. The USB Vendor ID is the value given to the

<code>SYSFS{idVendor}</code> property in the rules file, as described in step 3, above.</p>



<table>

  <tr>

    <th>Manufacturer</th><th>USB Vendor ID</th></tr>

  <tr>

    <td>Acer</td><td>0502</td></tr>

    <td>Acer</td>

    <td><code>0502</code></td></tr>

  <tr>

    <td>Dell</td>

    <td><code>413c</code></td></tr>

  <tr>

    <td>Foxconn</td>

    <td><code>0489</code></td></tr>

  <tr>

    <td>Garmin-Asus</td>

    <td><code>091E</code></td></tr>

  <tr>

    <td>HTC</td>

    <td><code>0bb4</code></td></tr>

  <tr>

    <td>HTC</td><td>0bb4</td></tr>

    <td>Huawei</td>

    <td><code>12d1</code></td></tr>

  <tr>

    <td>Huawei</td><td>12d1</td></tr>

    <td>Kyocera</td>

    <td><code>0482</code></td></tr>

  <tr>

    <td>LG</td><td>1004</td></tr>

    <td>LG</td>

    <td><code>1004</code></td></tr>

  <tr>

    <td>Motorola</td><td>22b8</td></tr>

    <td>Motorola</td>

    <td><code>22b8</code></td></tr>

  <tr>

    <td>Samsung</td><td>04e8</td></tr>

    <td>Nvidia</td>

    <td><code>0955</code></td></tr>

  <tr>

    <td>Sony Ericsson</td><td>0fce</td></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>

docs/html/guide/developing/eclipse-adt.jd

+92 −57
Original line number Diff line number Diff line
@@ -6,10 +6,11 @@ page.title=Developing In Eclipse, with ADT 
  <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="#CreatingAnAvd">Creating an AVD</a></li>

        <li><a href="#RunningAnApplication">Running an application</a></li>

        <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 Custom Run Configuration</a></li>
@@ -27,7 +28,8 @@ 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>

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>
@@ -70,7 +72,7 @@ Android project (or a project from existing code). To create a new project:</p> 
        The Build Target

        specifies which Android platform you'd like your application built against.

        <p>Unless you know that you'll be using new APIs introduced in the latest SDK, you should

        select a target with the lowest platform version possible, such as Android 1.1.</p>

        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
@@ -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. 

            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>

            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>

        </ul>

      </li>
@@ -133,70 +136,73 @@ folders and files in your new project:</p> 
  </dl>





<h2 id="Running">Running Your Application</h2>



<p>Before you can run your application on the Android Emulator, 

you <strong>must</strong> create an Android Virtual Device (AVD). 

An AVD is a configuration that specifies the Android platform to be used on the emulator.

You can read more 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>

<h2 id="AVD">Creating an AVD</h2>



<p>If you will be running your applications only on actual device hardware, you do not 

need an AVD &mdash; see 

<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> for information

on running your application.</p>

<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>



<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>

<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 (a black device)

    in the Eclipse toolbar.</p>

  <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 Virtual Devices panel, you'll see a list of existing AVDs. Click <strong>New</strong>

  to create a new AVD.</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 image (optional), and

    <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 close the AVD Manager. 

In the next section, you'll see how the AVD is used

when launching your application on an emulator.</p>

<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>





<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

you have created an AVD with a target that satisfies your application's Build Target. 

If an AVD cannot be found that meets the requirements of your Build Target, you will see

a console error telling you so and the launch will be aborted.</p>

<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>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 main menu. The ADT plugin

will automatically create a default launch configuration for the project.</p>

<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>When you choose to run or debug your application, Eclipse will perform the following:</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>

  <li>Compile the project (if there have been changes since the last build).</li>

  <li>Create a default launch configuration (if one does not already exist for the project).</li>

  <li>Install and start the application on an emulator or device (based on the Deployment Target

    defined by the run configuration).

    <p>By default, Android application run configurations use an "automatic target" mode for 

  <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>
@@ -206,14 +212,41 @@ will automatically create a default launch configuration for the project.</p> 
<p>If debugging, the application will start in the "Waiting For Debugger" mode. Once the

debugger is attached, Eclipse will open the Debug perspective.</p>



<p>To set or change the launch configuration used for your project, use the launch configuration manager. 

<p>To set or change the launch configuration used for your project, use the launch configuration

manager.

See <a href="#launchconfig">Creating a Launch Configuration</a> for information.</p>



<p>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>



<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.

The default run configuration will

launch the default project Activity and use automatic target mode for device selection
@@ -240,7 +273,8 @@ for your Eclipse version:</p> 
    <ul>

      <li>To create a new configuration:

        <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 

          <strong>New</strong>).</li>

          <li>Enter a Name for your configuration.</li>
@@ -268,7 +302,8 @@ document.</p> 


<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>



<ol>

docs/html/guide/developing/other-ide.jd

+134 −77

File changed.

Preview size limit exceeded, changes collapsed.

docs/html/sdk/installing.jd

+6 −4
Original line number Diff line number Diff line
@@ -361,7 +361,7 @@ applications against, each in a separate directory. </td> 
</tr>

<tr>

<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 

directories contain a similar set of files and subdirectory structure.</td>

</tr>
@@ -439,8 +439,8 @@ begin developing applications. Here are a few ways you can get started: </p> 


<p><strong>Set up the Hello World application</strong></p>

<ul>

  <li>If you have just installed the SDK for the first time, <a 

  href="{@docRoot}resources/tutorials/hello-world.html">go to the Hello

  <li>If you have just installed the SDK for the first time, go to the <a

  href="{@docRoot}resources/tutorials/hello-world.html">Hello

  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

  Virtual Device (AVD) on which to run the application.
@@ -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

  <a href="{@docRoot}guide/developing/other-ide.html">in other IDEs</a>

  </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>



<p><strong>Follow the Notepad tutorial</strong></p>