Doc change: restructuring changes for building and running section of dev guide

page.title=Building and Running Applications in Other IDEs

@jd:body

 <div id="qv-wrapper">

    <div id="qv">

      <h2>In this document</h2>

      <ol>

        <li><a href="#DebugMode">Building in debug mode</a></li>

        <li><a href="#ReleaseMode">Building in release mode</a></li>

        <li><a href="#RunningOnEmulator">Running on an emulator</a></li>

        <li><a href="#RunningOnDevice">Running on a device</a></li>

      </ol>

    </div>

  </div>

  <p>There are two ways to build your application using the Ant build script: one for

  testing/debugging your application &mdash; <em>debug mode</em> &mdash; and one for building your

  final package for release &mdash; <em>release mode</em>. Regardless of which way you build your application,

  it must be signed before it can install on an emulator or device—with a debug key when building

  in debug mode and with your own private key when building in release mode.</p>

  <p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile

  and build your project. This will create the .apk file that you can install on an emulator or device.

  When you build in debug mode, the .apk file is automatically signed by the SDK tools with

  a debug key, so it's instantly ready for installation onto an emulator or attached

  development device. You cannot distribute an application that is signed with a debug key.

  When you build in release mode, the .apk file is <em>unsigned</em>, so you

  must manually sign it with your own private key, using Keytool and Jarsigner.</p>

  <p>It's important that you read and understand <a href=

  "{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>, particularly once

  you're ready to release your application and share it with end-users. That document describes the

  procedure for generating a private key and then using it to sign your .apk file. If you're just

  getting started, however, you can quickly run your applications on an emulator or your own

  development device by building in debug mode.</p>

  <p>If you don't have Ant, you can obtain it from the <a href="http://ant.apache.org/">Apache Ant

  home page</a>. Install it and make sure it is in your executable PATH. Before calling Ant, you

  need to declare the JAVA_HOME environment variable to specify the path to where the JDK is

  installed.</p>

  <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install

  in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of

  the space. To fix the problem, you can specify the JAVA_HOME variable like this: 

  <pre>set JAVA_HOME=c:\Progra~1\Java\&lt;jdkdir&gt;

  </pre>

  The easiest solution, however, is to install JDK in a non-space directory, for example:

  <pre>c:\java\jdk1.6.0_02</pre>

  <h2 id="DebugMode">Building in debug mode</h2>

  <p>For immediate application testing and debugging, you can build your application in debug mode

  and immediately install it on an emulator. In debug mode, the build tools automatically sign your

  application with a debug key and optimize the package with {@code zipalign}.</p>

  <p>To build in debug mode:</p>

  <ol>

    <li>Open a command-line and navigate to the root of your project directory.</li>

    <li>Use Ant to compile your project in debug mode:

      <pre>

ant debug

</pre>

      <p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named

      <code>&lt;your_project_name&gt;-debug.apk</code>. The file is already signed with

      the debug key and has been aligned with

      <a href="{@docRoot}/guide/developing/tools/zipalign.html"><code>zipalign</code></a>.

      </p>

    </li>

  </ol>

  <p>Each time you change a source file or resource, you must run Ant again in order to package up

  the latest version of the application.</p>

  <p>To install and run your application on an emulator, see the following section about <a href=

  "#RunningOnEmulator">Running on the Emulator</a>.</p>

  <h2 id="ReleaseMode">Building in release mode</h2>

  <p>When you're ready to release and distribute your application to end-users, you must build your

  application in release mode. Once you have built in release mode, it's a good idea to perform

  additional testing and debugging with the final .apk.</p>

  <p>Before you start building your application in release mode, be aware that you must sign the

  resulting application package with your private key, and should then align it using the {@code

  zipalign} tool. There are two approaches to building in release mode: build an unsigned package

  in release mode and then manually sign and align the package, or allow the build script to sign

  and align the package for you.</p>

  <h3 id="ManualReleaseMode">Build unsigned</h3>

  <p>If you build your application <em>unsigned</em>, then you will need to manually sign and align

  the package.</p>

  <p>To build an <em>unsigned</em> .apk in release mode:</p>

  <ol>

    <li>Open a command-line and navigate to the root of your project directory.</li>

    <li>Use Ant to compile your project in release mode:

      <pre>

ant release

</pre>

    </li>

  </ol>

  <p>This creates your Android application .apk file inside the project <code>bin/</code>

  directory, named <code><em>&lt;your_project_name&gt;</em>-unsigned.apk</code>.</p>

  <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't

  be installed until signed with your private key.</p>

  <p>Once you have created the unsigned .apk, your next step is to sign the .apk with your private

  key and then align it with {@code zipalign}. To complete this procedure, read <a href=

  "{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>

  <p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users.

  You should test the final build on different devices or AVDs to ensure that it

  runs properly on different platforms.</p>

  <h3 id="AutoReleaseMode">Build signed and aligned</h3>

  <p>If you would like, you can configure the Android build script to automatically sign and align

  your application package. To do so, you must provide the path to your keystore and the name of

  your key alias in your project's {@code build.properties} file. With this information provided,

  the build script will prompt you for your keystore and alias password when you build in release

  mode and produce your final application package, which will be ready for distribution.</p>

  <p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that

  you enter during the build process <strong>will be visible</strong>. If you are concerned about

  your keystore and alias password being visible on screen, then you may prefer to perform the

  application signing manually, via Jarsigner (or a similar tool). To instead perform the signing

  procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with

  <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>

  <p>To specify your keystore and alias, open the project {@code build.properties} file (found in

  the root of the project directory) and add entries for {@code key.store} and {@code key.alias}.

  For example:</p>

  <pre>

key.store=path/to/my.keystore

key.alias=mykeystore

</pre>

  <p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p>

  <ol>

    <li>Open a command-line and navigate to the root of your project directory.</li>

    <li>Use Ant to compile your project in release mode:

      <pre>

ant release

</pre>

    </li>

    <li>When prompted, enter you keystore and alias passwords.

      <p class="caution"><strong>Caution:</strong> As described above, your password will be

      visible on the screen.</p>

    </li>

  </ol>

  <p>This creates your Android application .apk file inside the project <code>bin/</code>

  directory, named <code><em>&lt;your_project_name&gt;</em>-release.apk</code>. This .apk file has

  been signed with the private key specified in {@code build.properties} and aligned with {@code

  zipalign}. It's ready for installation and distribution.</p>

  <h3>Once built and signed in release mode</h3>

  <p>Once you have signed your application with a private key, you can install and run it on an

  <a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. You can 

  also try installing it onto a device from a web server. Simply upload the signed .apk to a web 

  site, then load the .apk URL in your Android web browser to download the application and begin 

  installation. (On your device, be sure you have enabled 

  <em>Settings &gt; Applications &gt; Unknown sources</em>.)</p>

  <h2 id="RunningOnEmulator">Running on the emulator</h2>

  <p>Before you can run your application on the Android Emulator, you must <a href=

  "{@docRoot}guide/developing/devices/managing-avds.html">create an AVD</a>.</p>

  <p>To run your application:</p>

  <ol>

    <li>

      <strong>Open the SDK and AVD Manager and launch a virtual device</strong>

      <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool with no

      arguments:</p>

      <pre>

android

</pre>

      <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p>

    </li>

    <li>

      <strong>Install your application</strong>

      <p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the

      emulator:</p>

      <pre>

adb install <em>&lt;path_to_your_bin&gt;</em>.apk

</pre>

      <p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/}

      directory after you build your application.</p>

      <p>If there is more than one emulator running, you must specify the emulator upon which to

      install the application, by its serial number, with the <code>-s</code> option. For

      example:</p>

      <pre>

adb -s emulator-5554 install <em>path/to/your/app</em>.apk

</pre>

      <p>To see a list of available device serial numbers, execute {@code adb devices}.</p>

    </li>

  </ol>

  <p>If you don't see your application on the emulator, try closing the emulator and launching the

  virtual device again from the SDK and AVD Manager. Sometimes when you install an application for the

  first time, it won't show up in the application launcher or be accessible by other applications.

  This is because the package manager usually examines manifests completely only on emulator

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

  <p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, you can

  build your application and install it on the emulator in one simple step. Navigate to the root of

  your project directory and use Ant to compile the project with <em>install mode</em>: <code>ant

  install</code>. This will build your application, sign it with the debug key, and install it on

  the currently running emulator.</p>

  <h2 id="RunningOnDevice">Running on a device</h2>

  <p>Before you can run your application on a device, you must perform some basic setup for your

  device:</p>

  <ul>

    <li>Ensure that your application is debuggable by setting the

    <code>android:debuggable</code> attribute of the <code>&lt;application&gt;</code>

    element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>

    <li>Enable USB Debugging on your device. You can find the setting on most Android devices by

    going to <strong>Settings > Applications > Development > USB debugging</strong>.</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 your device is set up and connected via USB, navigate to your SDK's <code>platform-tools/</code>

  directory and install the <code>.apk</code> on the device:</p>

  <pre>

adb -d install <em>path/to/your/app</em>.apk 

</pre>

  <p>The {@code -d} flag specifies that you want to use the attached device (in case you also have

  an emulator running).</p>

  <p>For more information on the tools used above, please see the following documents:</p>

  <ul>

    <li><a href="{@docRoot}guide/developing/tools/android.html">android Tool</a></li>

    <li><a href="{@docRoot}guide/developing/devices/emulator.html">Android Emulator</a></li>

    <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li>

  </ul>

  <h2 id="Signing">Application Signing</h2>

  <p>As you begin developing Android applications, understand that all Android applications must be

  digitally signed before the system will install them on an emulator or device. There are two ways

  to do this: with a <em>debug key</em> (for immediate testing on an emulator or development

  device) or with a <em>private key</em> (for application distribution).</p>

  <p>The Android build tools help you get started by automatically signing your .apk files with a

  debug key at build time. This means that you can compile your application and install it on the

  emulator without having to generate your own private key. However, please note that if you intend

  to publish your application, you <strong>must</strong> sign the application with your own private

  key, rather than the debug key generated by the SDK tools.</p>

  <p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key,

  prior to installing them on an emulator or development device. This means that you can quickly

  run your application from Eclipse without having to generate your own private key. No specific

  action on your part is needed, provided ADT has access to Keytool.However, please note that if

  you intend to publish your application, you <strong>must</strong> sign the application with your

  own private key, rather than the debug key generated by the SDK tools.</p>

  <p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your

  Applications</a>, which provides a thorough guide to application signing on Android and what it

  means to you as an Android application developer. The document also includes a guide to exporting

  and signing your application with the ADT's Export Wizard.</p>

 No newline at end of file

page.title=Building and Running Applications in Eclipse

@jd:body

<div id="qv-wrapper">

    <div id="qv">

      <h2>In this document</h2>

      <ol>

        <li><a href="#RunningOnEmulatorEclipse">Running on an Emulator</a></li>

        <li><a href="#RunningOnDeviceEclipse">Running on a Device</a></li>

        <li><a href="#RunConfig">Creating a Run Configuration</a></li>

      </ol>

    </div>

  </div>

  <p>Eclipse and ADT provide an environment where most of the details of the build process are

  hidden from you. By default, the build process constantly runs in the background as you make

  changes to your project.</p>

  <p>When Eclipse automatically builds your application, it enables debugging and signs the

  <code>.apk</code> with a debug key, by default. When you run the application,

  Eclipse invokes ADB and installs your application to a device or emulator, so you do not have to

  manually perform these tasks. Since most of the build process is taken care of by Eclipse, the

  following topics show you how to run an application, which will automatically build your

  application as well.</p>

  <p>To distribute your application, however, you must build your application in release mode and sign the

  <code>.apk</code> file with your own private key.</p>

   <p>This document shows you how to run your application on an emulator or a real device 

   from Eclipse—all of which is done using the debug version of your application. 

   For more information about how to sign your application with a private key for release, see <a href=

  "{@docRoot}guide/publishing/app-signing.html#ExportWizard">Signing Your Applications</a></p>

  <h2 id="RunningOnEmulatorEclipse">Running on the emulator</h2>

  <p>Before you can run your application on the Android Emulator, you must <a href=

  "{@docRoot}guide/developing/devices/managing-avds.html">create an AVD</a>.</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 run 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 run 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>

    </li>

  </ol>

  <p>If you run the application with the Debug option, the application will start in the "Waiting For Debugger" mode. Once the debugger

  is attached, Eclipse opens the Debug perspective and starts the application's main activity. Otherwise, if you run the

  application with the normal Run option, Eclipse installs the application on the device and launches the main activity.</p>

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

  manager. See the section below about <a href="#RunConfig">Creating a Run Configuration</a> for more 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>

  <h2 id="RunningOnDeviceEclipse">Running on a device</h2>

  <p>Before you can run your application on a device, you must perform some basic setup for your

  device:</p>

  <ul>

    <li>Ensure that your application is debuggable by setting the

    <code>android:debuggable</code> attribute of the <code>&lt;application&gt;</code>

    element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>

    <li>Enable USB Debugging on your device. You can find the setting on most Android devices by

    going to <strong>Settings > Applications > Development > USB debugging</strong>.</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">Connecting Hardware Devices</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 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 (with no preferred AVD). If the default settings don't suit your project, you can

  customize the run configuration or even create a new one.</p>

  <p>To create or modify a run configuration, refer to the Eclipse documentation on how to create Run configurations.

  The following steps highlight the important things you need to do for an Android project:</p>

  <ol>

    <li>Open the run configuration manager from the Run Menu.</li>

    <li>Expand the <strong>Android Application</strong> item and create a new configuration or open

    an existing one.

    </li>

    <li>With the Run Configuration selected, adjust your desired run configuration settings:

      <ul>

      <li>In the Android tab, specify the Project and Activity to launch.

      </li>

      <li><p>In the Target tab, consider whether you'd like to use Manual or Automatic mode when

      selecting an AVD to run your application. See the following section on <a href=

      "#AutoAndManualTargetModes">Automatic and manual target modes</a>).</p>

      <p>You can specify any emulator options to the Additional Emulator Command Line Options

      field. For example, you could add <code>-scale 96dpi</code> to scale the AVD's screen to an

      accurate size, based on the dpi of your computer monitor. For a full list of emulator

      options, see the <a href="{@docRoot}guide/developing/tools/emulator.html">Android

      Emulator</a> document.</p>

      </li>

      </ul>

    </li>

  </ol>

  <h4 id="AutoAndManualTargetModes">Automatic and manual target modes</h4>

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

    <li>If there's a device or emulator already running and its AVD configuration meets the

    requirements of the application's build target, the application is installed and run upon

    it.</li>

    <li>If there's more than one device or emulator running, each of which meets the requirements

    of the build target, a "device chooser" is shown to let you select which device to use.</li>

    <li>If there are no devices or emulators running that meet the requirements of the build

    target, ADT looks at the available AVDs. If there is an AVD that matches the build target of the project,

    ADT chooses that AVD. If the AVD versions are newer than the build target of the project, ADT chooses

    the oldest possible version of an AVD that meets the project's build target requirement.</li>

    <li>If there are no suitable AVDs, the application is not installed a console error warning tells

    you that there is no existing AVD that meets the build target requirements.</li>

  </ol>

  <p>However, if a "preferred AVD" is selected in the run configuration, then the application will

  <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator will be

  launched.</p>

  <p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" is

  presented every time that your application is run, so that you can select which AVD to use.</p>

 No newline at end of file