1page.title=Running Your App 2parent.title=Building Your First App 3parent.link=index.html 4 5trainingnavtop=true 6previous.title=Creating a Project 7previous.link=creating-project.html 8next.title=Building a Simple User Interface 9next.link=building-ui.html 10 11@jd:body 12 13 14<!-- This is the training bar --> 15<div id="tb-wrapper"> 16<div id="tb"> 17 18<h2>This lesson teaches you to</h2> 19 20<ol> 21 <li><a href="#RealDevice">Run on a Real Device</a></li> 22 <li><a href="#Emulator">Run on the Emulator</a></li> 23</ol> 24 25<h2>You should also read</h2> 26 27<ul> 28 <li><a href="{@docRoot}tools/device.html">Using Hardware Devices</a></li> 29 <li><a href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a></li> 30 <li><a href="{@docRoot}tools/projects/index.html">Managing Projects</a></li> 31</ul> 32 33 34</div> 35</div> 36 37 38<p>If you followed the <a href="creating-project.html">previous lesson</a> to create an 39Android project, it includes a default set of "Hello World" source files that allow you to 40immediately run the app.</p> 41 42<p>How you run your app depends on two things: whether you have a real Android-powered device and 43whether you're using Eclipse. This lesson shows you how to install and run your app on a 44real device and on the Android emulator, and in both cases with either Eclipse or the command line 45tools.</p> 46 47<p>Before you run your app, you should be aware of a few directories and files in the Android 48project:</p> 49 50<dl> 51 <dt><code>AndroidManifest.xml</code></dt> 52 <dd>The <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest file</a> describes 53the fundamental characteristics of the app and defines each of 54its components. You'll learn about various declarations in this file as you read more training 55classes. 56 <p>One of the most important elements your manifest should include is the <a 57href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> 58element. This declares your app's compatibility with different Android versions using the <a 59href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 60and <a 61href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> 62attributes. For your first app, it should look like this:</p> 63<pre> 64<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... > 65 <uses-sdk android:minSdkVersion="8" android:targetSdkVersion="19" /> 66 ... 67</manifest> 68</pre> 69<p>You should always set the <a 70href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> 71as high as possible and test your app on the corresponding platform version. For more information, 72read <a href="{@docRoot}training/basics/supporting-devices/platforms.html">Supporting Different 73Platform Versions</a>.</p> 74 75 </dd> 76 <dt><code>src/</code></dt> 77 <dd>Directory for your app's main source files. By default, it includes an {@link 78android.app.Activity} class that runs when your app is launched using the app icon.</dd> 79 <dt><code>res/</code></dt> 80 <dd>Contains several sub-directories for <a 81href="{@docRoot}guide/topics/resources/overview.html">app resources</a>. Here are just a few: 82 <dl style="margin-top:1em"> 83 <dt><code>drawable-hdpi/</code></dt> 84 <dd>Directory for drawable objects (such as bitmaps) that are designed for high-density 85(hdpi) screens. Other drawable directories contain assets designed for other screen densities.</dd> 86 <dt><code>layout/</code></dt> 87 <dd>Directory for files that define your app's user interface.</dd> 88 <dt><code>values/</code></dt> 89 <dd>Directory for other various XML files that contain a collection of resources, such as 90string and color definitions.</dd> 91 </dl> 92 </dd> 93</dl> 94 95<p>When you build and run the default Android app, the default {@link android.app.Activity} 96class starts and loads a layout file 97that says "Hello World." The result is nothing exciting, but it's 98important that you understand how to run your app before you start developing.</p> 99 100 101 102<h2 id="RealDevice">Run on a Real Device</h2> 103 104<p>If you have a real Android-powered device, here's how you can install and run your app:</p> 105 106<ol> 107 <li>Plug in your device to your development machine with a USB cable. 108If you're developing on Windows, you might need to install the appropriate USB driver for your 109device. For help installing drivers, see the <a href="{@docRoot}tools/extras/oem-usb.html">OEM USB 110Drivers</a> document.</li> 111 <li>Enable <strong>USB debugging</strong> on your device. 112 <ul> 113 <li>On most devices running Android 3.2 or older, you can find the option under 114 <strong>Settings > Applications > Development</strong>.</li> 115 <li>On Android 4.0 and newer, it's in <strong>Settings > Developer options</strong>. 116 <p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer 117 options</strong> is hidden by default. To make it available, go 118 to <strong>Settings > About phone</strong> and tap <strong>Build number</strong> 119 seven times. Return to the previous screen to find <strong>Developer options</strong>.</p> 120 </li> 121 </ul> 122 </li> 123</ol> 124 125<p>To run the app from Eclipse:</p> 126<ol> 127 <li>Open one of your project's files and click 128<strong>Run</strong> <img 129src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" /> 130from the toolbar.</li> 131 <li>In the <strong>Run as</strong> window that appears, select 132 <strong>Android Application</strong> and click <strong>OK</strong>.</li> 133</ol> 134<p>Eclipse installs the app on your connected device and starts it.</p> 135 136 137<p>Or to run your app from a command line:</p> 138 139<ol> 140 <li>Change directories to the root of your Android project and execute: 141<pre class="no-pretty-print">ant debug</pre></li> 142 <li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your 143<code>PATH</code> environment variable, then execute: 144<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li> 145 <li>On your device, locate <em>MyFirstActivity</em> and open it.</li> 146</ol> 147 148<p>That's how you build and run your Android app on a device! 149 To start developing, continue to the <a href="building-ui.html">next 150lesson</a>.</p> 151 152 153 154<h2 id="Emulator">Run on the Emulator</h2> 155 156<p>Whether you're using Eclipse or the command line, to run your app on the emulator you need to 157first create an <a href="{@docRoot}tools/devices/index.html">Android Virtual Device</a> (AVD). An 158AVD is a device configuration for the Android emulator that allows you to model different 159devices.</p> 160 161<div class="figure" style="width:457px"> 162 <img src="{@docRoot}images/screens_support/avds-config.png" alt="" /> 163 <p class="img-caption"><strong>Figure 1.</strong> The AVD Manager showing a few virtual 164devices.</p> 165</div> 166 167<p>To create an AVD:</p> 168<ol> 169 <li>Launch the Android Virtual Device Manager: 170 <ol type="a"> 171 <li>In Eclipse, click Android Virtual Device Manager 172 <img src="{@docRoot}images/tools/avd_manager.png" 173style="vertical-align:baseline;margin:0" /> from the toolbar.</li> 174 <li>From the command line, change 175directories to <code><sdk>/tools/</code> and execute: 176<pre class="no-pretty-print">android avd</pre></li> 177 </ol> 178 </li> 179 <li>In the <em>Android Virtual Device Manager</em> panel, click <strong>New</strong>.</li> 180 <li>Fill in the details for the AVD. 181Give it a name, a platform target, an SD card size, and a skin (HVGA is default).</li> 182 <li>Click <strong>Create AVD</strong>.</li> 183 <li>Select the new AVD from the <em>Android Virtual Device Manager</em> and click 184<strong>Start</strong>.</li> 185 <li>After the emulator boots up, unlock the emulator screen.</li> 186</ol> 187 188<p>To run the app from Eclipse:</p> 189<ol> 190 <li>Open one of your project's files and click 191<strong>Run</strong> <img 192src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" /> 193from the toolbar.</li> 194 <li>In the <strong>Run as</strong> window that appears, select 195 <strong>Android Application</strong> and click <strong>OK</strong>.</li> 196</ol> 197<p>Eclipse installs the app on your AVD and starts it.</p> 198 199 200<p>Or to run your app from the command line:</p> 201 202<ol> 203 <li>Change directories to the root of your Android project and execute: 204<pre class="no-pretty-print">ant debug</pre></li> 205 <li>Make sure the Android SDK <code>platform-tools/</code> directory is included in your 206<code>PATH</code> environment 207variable, then execute: 208<pre class="no-pretty-print">adb install bin/MyFirstApp-debug.apk</pre></li> 209 <li>On the emulator, locate <em>MyFirstActivity</em> and open it.</li> 210</ol> 211 212 213<p>That's how you build and run your Android app on the emulator! 214 To start developing, continue to the <a href="building-ui.html">next 215lesson</a>.</p> 216 217 218 219 220 221 222 223 224 225 226 227
