1 page.title=Running Your App 2 parent.title=Building Your First App 3 parent.link=index.html 4 5 trainingnavtop=true 6 previous.title=Creating a Project 7 previous.link=creating-project.html 8 next.title=Building a Simple User Interface 9 next.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 39 Android project, it includes a default set of "Hello World" source files that allow you to 40 immediately 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 43 whether you're using Eclipse. This lesson shows you how to install and run your app on a 44 real device and on the Android emulator, and in both cases with either Eclipse or the command line 45 tools.</p> 46 47 <p>Before you run your app, you should be aware of a few directories and files in the Android 48 project:</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 53 the fundamental characteristics of the app and defines each of 54 its components. You'll learn about various declarations in this file as you read more training 55 classes. 56 <p>One of the most important elements your manifest should include is the <a 57 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> 58 element. This declares your app's compatibility with different Android versions using the <a 59 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 60 and <a 61 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> 62 attributes. 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="17" /> 66 ... 67 </manifest> 68 </pre> 69 <p>You should always set the <a 70 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> 71 as high as possible and test your app on the corresponding platform version. For more information, 72 read <a href="{@docRoot}training/basics/supporting-devices/platforms.html">Supporting Different 73 Platform 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 78 android.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 81 href="{@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 90 string 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} 96 class starts and loads a layout file 97 that says "Hello World." The result is nothing exciting, but it's 98 important 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. 108 If you're developing on Windows, you might need to install the appropriate USB driver for your 109 device. For help installing drivers, see the <a href="{@docRoot}tools/extras/oem-usb.html">OEM USB 110 Drivers</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 129 src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" /> 130 from 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 150 lesson</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 157 first create an <a href="{@docRoot}tools/devices/index.html">Android Virtual Device</a> (AVD). An 158 AVD is a device configuration for the Android emulator that allows you to model different 159 devices.</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 164 devices.</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" 173 style="vertical-align:baseline;margin:0" /> from the toolbar.</li> 174 <li>From the command line, change 175 directories 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. 181 Give 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 192 src="{@docRoot}images/tools/eclipse-run.png" style="vertical-align:baseline;margin:0" /> 193 from 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 207 variable, 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 215 lesson</a>.</p> 216 217 218 219 220 221 222 223 224 225 226 227
