1page.title=Building and Running from the Command Line 2parent.title=Building and Running 3parent.link=index.html 4@jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li><a href="#DebugMode">Building in Debug Mode</a></li> 11 <li><a href="#ReleaseMode">Building in Release Mode</a> 12 <ol> 13 <li><a href="#ManualReleaseMode">Build unsigned</a></li> 14 <li><a href="#AutoReleaseMode">Build signed and aligned</a></li> 15 <li><a href="#OnceBuilt">Once built and signed in release mode</a></li> 16 </ol> 17 </li> 18 <li><a href="#RunningOnEmulator">Running on the Emulator</a></li> 19 <li><a href="#RunningOnDevice">Running on a Device</a></li> 20 <li><a href="#Signing">Application Signing</a></li> 21 <li><a href="#AntReference">Ant Command Reference</a></li> 22 </ol> 23 <h2>See also</h2> 24 <ol> 25 <li><a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from 26the Command Line</a></li> 27 <li><a href="{@docRoot}tools/devices/emulator.html">Using the Android 28Emulator</a></li> 29 <li><a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a></li> 30 </ol> 31 </div> 32 </div> 33 34 <p>There are two ways to build your application using the Ant build script: one for 35 testing/debugging your application — <em>debug mode</em> — and one for building your 36 final package for release — <em>release mode</em>. Regardless of which way you build your application, 37 it must be signed before it can install on an emulator or device—with a debug key when building 38 in debug mode and with your own private key when building in release mode.</p> 39 40 <p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile 41 and build your project. This will create the .apk file that you can install on an emulator or device. 42 When you build in debug mode, the .apk file is automatically signed by the SDK tools with 43 a debug key, so it's instantly ready for installation onto an emulator or attached 44 development device. You cannot distribute an application that is signed with a debug key. 45 When you build in release mode, the .apk file is <em>unsigned</em>, so you 46 must manually sign it with your own private key, using Keytool and Jarsigner.</p> 47 48 <p>It's important that you read and understand <a href= 49 "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>, particularly once 50 you're ready to release your application and share it with end-users. That document describes the 51 procedure for generating a private key and then using it to sign your .apk file. If you're just 52 getting started, however, you can quickly run your applications on an emulator or your own 53 development device by building in debug mode.</p> 54 55 <p>If you don't have Ant, you can obtain it from the <a href="http://ant.apache.org/">Apache Ant 56 home page</a>. Install it and make sure it is in your executable PATH. Before calling Ant, you 57 need to declare the JAVA_HOME environment variable to specify the path to where the JDK is 58 installed.</p> 59 60 <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install 61 in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of 62 the space. To fix the problem, you can specify the JAVA_HOME variable like this: 63 <pre>set JAVA_HOME=c:\Progra~1\Java\<jdkdir></pre> 64 65 <p>The easiest solution, however, is to install JDK in a non-space directory, for example:</p> 66 67 <pre>c:\java\jdk1.6.0_02</pre> 68 69 <h2 id="DebugMode">Building in Debug Mode</h2> 70 71 <p>For immediate application testing and debugging, you can build your application in debug mode 72 and immediately install it on an emulator. In debug mode, the build tools automatically sign your 73 application with a debug key and optimize the package with {@code zipalign}.</p> 74 75 <p>To build in debug mode:</p> 76 77 <ol> 78 <li>Open a command-line and navigate to the root of your project directory.</li> 79 <li>Use Ant to compile your project in debug mode: 80 <pre> 81ant debug 82</pre> 83 84 <p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named 85 <code><your_project_name>-debug.apk</code>. The file is already signed with 86 the debug key and has been aligned with 87 <a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>. 88 </p> 89 </li> 90 </ol> 91 92 <p>Each time you change a source file or resource, you must run Ant again in order to package up 93 the latest version of the application.</p> 94 95 <p>To install and run your application on an emulator, see the following section about <a href= 96 "#RunningOnEmulator">Running on the Emulator</a>.</p> 97 98 <h2 id="ReleaseMode">Building in Release Mode</h2> 99 100 <p>When you're ready to release and distribute your application to end-users, you must build your 101 application in release mode. Once you have built in release mode, it's a good idea to perform 102 additional testing and debugging with the final .apk.</p> 103 104 <p>Before you start building your application in release mode, be aware that you must sign the 105 resulting application package with your private key, and should then align it using the {@code 106 zipalign} tool. There are two approaches to building in release mode: build an unsigned package 107 in release mode and then manually sign and align the package, or allow the build script to sign 108 and align the package for you.</p> 109 110 <h3 id="ManualReleaseMode">Build unsigned</h3> 111 112 <p>If you build your application <em>unsigned</em>, then you will need to manually sign and align 113 the package.</p> 114 115 <p>To build an <em>unsigned</em> .apk in release mode:</p> 116 117 <ol> 118 <li>Open a command-line and navigate to the root of your project directory.</li> 119 120 <li>Use Ant to compile your project in release mode: 121 <pre> 122ant release 123</pre> 124 </li> 125 </ol> 126 127 <p>This creates your Android application .apk file inside the project <code>bin/</code> 128 directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p> 129 130 <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't 131 be installed until signed with your private key.</p> 132 133 <p>Once you have created the unsigned .apk, your next step is to sign the .apk with your private 134 key and then align it with {@code zipalign}. To complete this procedure, read <a href= 135 "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p> 136 137 <p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users. 138 You should test the final build on different devices or AVDs to ensure that it 139 runs properly on different platforms.</p> 140 141 <h3 id="AutoReleaseMode">Build signed and aligned</h3> 142 143 <p>If you would like, you can configure the Android build script to automatically sign and align 144 your application package. To do so, you must provide the path to your keystore and the name of 145 your key alias in your project's {@code ant.properties} file. With this information provided, 146 the build script will prompt you for your keystore and alias password when you build in release 147 mode and produce your final application package, which will be ready for distribution.</p> 148 149 <p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that 150 you enter during the build process <strong>will be visible</strong>. If you are concerned about 151 your keystore and alias password being visible on screen, then you may prefer to perform the 152 application signing manually, via Jarsigner (or a similar tool). To instead perform the signing 153 procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with 154 <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p> 155 156 <p>To specify your keystore and alias, open the project {@code ant.properties} file (found in 157 the root of the project directory) and add entries for {@code key.store} and {@code key.alias}. 158 For example:</p> 159 <pre> 160key.store=path/to/my.keystore 161key.alias=mykeystore 162</pre> 163 164 <p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p> 165 166 <ol> 167 <li>Open a command-line and navigate to the root of your project directory.</li> 168 169 <li>Use Ant to compile your project in release mode: 170 <pre> 171ant release 172</pre> 173 </li> 174 175 <li>When prompted, enter you keystore and alias passwords. 176 177 <p class="caution"><strong>Caution:</strong> As described above, your password will be 178 visible on the screen.</p> 179 </li> 180 </ol> 181 182 <p>This creates your Android application .apk file inside the project <code>bin/</code> 183 directory, named <code><em><your_project_name></em>-release.apk</code>. This .apk file has 184 been signed with the private key specified in {@code ant.properties} and aligned with {@code 185 zipalign}. It's ready for installation and distribution.</p> 186 187 <h3 id="OnceBuilt">Once built and signed in release mode</h3> 188 189 <p>Once you have signed your application with a private key, you can install and run it on an 190 <a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. You can 191 also try installing it onto a device from a web server. Simply upload the signed .apk to a web 192 site, then load the .apk URL in your Android web browser to download the application and begin 193 installation. (On your device, be sure you have enabled 194 <em>Settings > Applications > Unknown sources</em>.)</p> 195 196 <h2 id="RunningOnEmulator">Running on the Emulator</h2> 197 198 <p>Before you can run your application on the Android Emulator, you must <a href= 199 "{@docRoot}tools/devices/managing-avds.html">create an AVD</a>.</p> 200 201 <p>To run your application:</p> 202 203 <ol> 204 <li> 205 <strong>Open the AVD Manager and launch a virtual device</strong> 206 207 <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool 208with the <code>avd</code> options:</p> 209 <pre> 210android avd 211</pre> 212 213 <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p> 214 </li> 215 216 <li> 217 <strong>Install your application</strong> 218 219 <p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the 220 emulator:</p> 221 <pre> 222adb install <em><path_to_your_bin></em>.apk 223</pre> 224 225 <p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/} 226 directory after you build your application.</p> 227 228 <p>If there is more than one emulator running, you must specify the emulator upon which to 229 install the application, by its serial number, with the <code>-s</code> option. For 230 example:</p> 231 <pre> 232adb -s emulator-5554 install <em>path/to/your/app</em>.apk 233</pre> 234 235 <p>To see a list of available device serial numbers, execute {@code adb devices}.</p> 236 </li> 237 </ol> 238 239 <p>If you don't see your application on the emulator, try closing the emulator and launching the 240 virtual device again from the AVD Manager. Sometimes when you install an application for the 241 first time, it won't show up in the application launcher or be accessible by other applications. 242 This is because the package manager usually examines manifests completely only on emulator 243 startup.</p> 244 245 <p>Be certain to create multiple AVDs upon which to test your application. You should have one 246 AVD for each platform and screen type with which your application is compatible. For instance, if 247 your application compiles against the Android 4.0 (API Level 14) platform, you should create an 248 AVD for each platform equal to and greater than 4.0 and an AVD for each <a href= 249 "{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your 250 application on each one.</p> 251 252 <p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, you can 253 build your application and install it on the emulator in one simple step. Navigate to the root of 254 your project directory and use Ant to compile the project with <em>install mode</em>: <code>ant 255 install</code>. This will build your application, sign it with the debug key, and install it on 256 the currently running emulator.</p> 257 258 <h2 id="RunningOnDevice">Running on a Device</h2> 259 260 <p>Before you can run your application on a device, you must perform some basic setup for your 261 device:</p> 262 263 <ul> 264 <li>Enable <strong>USB debugging</strong> on your device. 265 <ul> 266 <li>On most devices running Android 3.2 or older, you can find the option under 267 <strong>Settings > Applications > Development</strong>.</li> 268 <li>On Android 4.0 and newer, it's in <strong>Settings > Developer options</strong>. 269 <p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer 270 options</strong> is hidden by default. To make it available, go 271 to <strong>Settings > About phone</strong> and tap <strong>Build number</strong> 272 seven times. Return to the previous screen to find <strong>Developer options</strong>.</p> 273 </li> 274 </ul> 275 </li> 276 277 <li>Ensure that your development computer can detect your device when connected via USB</li> 278 </ul> 279 280 <p>Read <a href="{@docRoot}tools/device.html#setting-up">Setting up a Device for 281 Development</a> for more information.</p> 282 283 <p>Once your device is set up and connected via USB, navigate to your SDK's <code>platform-tools/</code> 284 directory and install the <code>.apk</code> on the device:</p> 285 <pre> 286adb -d install <em>path/to/your/app</em>.apk 287</pre> 288 289 <p>The {@code -d} flag specifies that you want to use the attached device (in case you also have 290 an emulator running).</p> 291 292 <p>For more information on the tools used above, please see the following documents:</p> 293 294 <ul> 295 <li><a href="{@docRoot}tools/help/android.html">android Tool</a></li> 296 297 <li><a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a></li> 298 299 <li><a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (ADB)</li> 300 </ul> 301 302 <h2 id="Signing">Application Signing</h2> 303 304 <p>As you begin developing Android applications, understand that all Android applications must be 305 digitally signed before the system will install them on an emulator or device. There are two ways 306 to do this: with a <em>debug key</em> (for immediate testing on an emulator or development 307 device) or with a <em>private key</em> (for application distribution).</p> 308 309 <p>The Android build tools help you get started by automatically signing your .apk files with a 310 debug key at build time. This means that you can compile your application and install it on the 311 emulator without having to generate your own private key. However, please note that if you intend 312 to publish your application, you <strong>must</strong> sign the application with your own private 313 key, rather than the debug key generated by the SDK tools.</p> 314 315 <p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key, 316 prior to installing them on an emulator or development device. This means that you can quickly 317 run your application from Eclipse without having to generate your own private key. No specific 318 action on your part is needed, provided ADT has access to Keytool. However, please note that if 319 you intend to publish your application, you <strong>must</strong> sign the application with your 320 own private key, rather than the debug key generated by the SDK tools.</p> 321 322 <p>Please read <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your 323 Applications</a>, which provides a thorough guide to application signing on Android and what it 324 means to you as an Android application developer. The document also includes a guide to exporting 325 and signing your application with the ADT's Export Wizard.</p> 326 327 <h2 id="AntReference">Ant Command Reference</h2> 328 <dt><code>ant clean</code></dt> 329 <dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code> 330(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a 331test project, the tested project is also cleaned.</dd> 332 333 <dt><code>ant debug</code></dt> 334 <dd>Builds a debug package. Works on application, library, and test projects and compiles 335 dependencies as needed.</dd> 336 337 <dt id="emma"><code>ant emma debug</code></dt> 338 <dd>Builds a test project while building the tested project with instrumentation turned on. 339 This is used to run tests with code coverage enabled.</dd> 340 341 <dt><code>ant release</code></dt> 342 <dd>Builds a release package.</dd> 343 344 <dt><code>ant instrument</code> 345 </dt> 346 <dd>Builds an instrumented debug package. This is generally called automatically when building a 347 test project with code coverage enabled (with the <code>emma</code> 348 target)</dd> 349 350 <dt><code>ant <build_target> install</code></dt> 351 <dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd> 352 353 <dt><code>ant installd</code></dt> 354 <dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not 355 already built.</dd> 356 357 <dt><code>ant installr</code></dt> 358 <dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not 359 already built.</dd> 360 361 <dt><code>ant installt</code></dt> 362 <dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the 363 tested application. This fails if the <code>.apk</code> is not already built.</dd> 364 365 <dt><code>ant installi</code></dt> 366 <dd>Installs an already compiled instrumented package. This is generally not used manually as 367 it's called when installing a test package. This fails if the <code>.apk</code> is not already 368 built.</dd> 369 370 <dt><code>ant test</code></dt> 371 <dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be 372 previously installed.</dd> 373 374 <dt><code>ant debug installt test</code></dt> 375 <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and 376 runs the tests.</dd> 377 378 <dt><code>ant emma debug install test</code></dt> 379 <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and 380 runs the tests with code coverage enabled.</dd> 381 382