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