Massive clobber of all HTML files in developer docs for new site design
Change-Id: Idc55a0b368c1d2c1e7d4999601b739dd57f08eb3
diff --git a/docs/html/tools/building/building-cmdline.jd b/docs/html/tools/building/building-cmdline.jd
new file mode 100644
index 0000000..6154d96
--- /dev/null
+++ b/docs/html/tools/building/building-cmdline.jd
@@ -0,0 +1,371 @@
+page.title=Building and Running from the Command Line
+parent.title=Building and Running
+parent.link=index.html
+@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>
+ <ol>
+ <li><a href="#ManualReleaseMode">Build unsigned</a></li>
+ <li><a href="#AutoReleaseMode">Build signed and aligned</a></li>
+ <li><a href="#OnceBuilt">Once built and signed in release mode</a></li>
+ </ol>
+ </li>
+ <li><a href="#RunningOnEmulator">Running on the Emulator</a></li>
+ <li><a href="#RunningOnDevice">Running on a Device</a></li>
+ <li><a href="#Signing">Application Signing</a></li>
+ <li><a href="#AntReference">Ant Command Reference</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from
+the Command Line</a></li>
+ <li><a href="{@docRoot}tools/devices/emulator.html">Using the Android
+Emulator</a></li>
+ <li><a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</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 — <em>debug mode</em> — and one for building your
+ final package for release — <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}tools/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\<jdkdir></pre>
+
+ <p>The easiest solution, however, is to install JDK in a non-space directory, for example:</p>
+
+ <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><your_project_name>-debug.apk</code>. The file is already signed with
+ the debug key and has been aligned with
+ <a href="{@docRoot}tools/help/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><your_project_name></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}tools/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 ant.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}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
+
+ <p>To specify your keystore and alias, open the project {@code ant.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><your_project_name></em>-release.apk</code>. This .apk file has
+ been signed with the private key specified in {@code ant.properties} and aligned with {@code
+ zipalign}. It's ready for installation and distribution.</p>
+
+ <h3 id="OnceBuilt">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 > Applications > 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}tools/devices/managing-avds.html">create an AVD</a>.</p>
+
+ <p>To run your application:</p>
+
+ <ol>
+ <li>
+ <strong>Open the AVD Manager and launch a virtual device</strong>
+
+ <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool
+with the <code>avd</code> options:</p>
+ <pre>
+android avd
+</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><path_to_your_bin></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 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>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}tools/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}tools/help/android.html">android Tool</a></li>
+
+ <li><a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a></li>
+
+ <li><a href="{@docRoot}tools/help/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}tools/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>
+
+ <h2 id="AntReference">Ant Command Reference</h2>
+ <dt><code>ant clean</code></dt>
+ <dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code>
+(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a
+test project, the tested project is also cleaned.</dd>
+
+ <dt><code>ant debug</code></dt>
+ <dd>Builds a debug package. Works on application, library, and test projects and compiles
+ dependencies as needed.</dd>
+
+ <dt id="emma"><code>ant emma debug</code></dt>
+ <dd>Builds a test project while building the tested project with instrumentation turned on.
+ This is used to run tests with code coverage enabled.</dd>
+
+ <dt><code>ant release</code></dt>
+ <dd>Builds a release package.</dd>
+
+ <dt><code>ant instrument</code>
+ </dt>
+ <dd>Builds an instrumented debug package. This is generally called automatically when building a
+ test project with code coverage enabled (with the <code>emma</code>
+ target)</dd>
+
+ <dt><code>ant <build_target> install</code></dt>
+ <dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd>
+
+ <dt><code>ant installd</code></dt>
+ <dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not
+ already built.</dd>
+
+ <dt><code>ant installr</code></dt>
+ <dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not
+ already built.</dd>
+
+ <dt><code>ant installt</code></dt>
+ <dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the
+ tested application. This fails if the <code>.apk</code> is not already built.</dd>
+
+ <dt><code>ant installi</code></dt>
+ <dd>Installs an already compiled instrumented package. This is generally not used manually as
+ it's called when installing a test package. This fails if the <code>.apk</code> is not already
+ built.</dd>
+
+ <dt><code>ant test</code></dt>
+ <dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be
+ previously installed.</dd>
+
+ <dt><code>ant debug installt test</code></dt>
+ <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
+ runs the tests.</dd>
+
+ <dt><code>ant emma debug install test</code></dt>
+ <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
+ runs the tests with code coverage enabled.</dd>
+
diff --git a/docs/html/tools/building/building-eclipse.jd b/docs/html/tools/building/building-eclipse.jd
new file mode 100644
index 0000000..c73fe97
--- /dev/null
+++ b/docs/html/tools/building/building-eclipse.jd
@@ -0,0 +1,165 @@
+page.title=Building and Running from Eclipse with ADT
+parent.title=Building and Running
+parent.link=index.html
+@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}tools/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}tools/devices/managing-avds.html">create an AVD</a>.</p>
+
+ <p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or
+ <strong>Run</strong> > <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><application></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}tools/device.html">Using 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> > <strong>Run</strong> (or <strong>Run</strong> >
+ <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}tools/help/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
diff --git a/docs/html/tools/building/index.jd b/docs/html/tools/building/index.jd
new file mode 100644
index 0000000..c64942f
--- /dev/null
+++ b/docs/html/tools/building/index.jd
@@ -0,0 +1,81 @@
+page.title=Building and Running
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#detailed-build">A Detailed Look at the Build Process</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>During the build process, your Android projects are compiled and packaged into an .apk file,
+ the container for your application binary. It contains all of the information necessary to run
+ your application on a device or emulator, such as compiled <code>.dex</code> files (<code>.class</code> files
+ converted to Dalvik byte code), a binary version of the <code>AndroidManifest.xml</code> file, compiled
+ resources (<code>resources.arsc</code>) and uncompiled resource files for your application.</p>
+
+ <p>If you are developing in Eclipse, the ADT plugin incrementally builds your project as you
+ make changes to the source code. Eclipse outputs an <code>.apk</code> file automatically to the bin folder of
+ the project, so you do not have to do anything extra to generate the <code>.apk</code>.</p>
+
+ <p>If you are developing in a non-Eclipse environment, you can build your project with the
+ generated <code>build.xml</code> Ant file that is in the project directory. The Ant file calls targets that
+ automatically call the build tools for you.</p>
+
+ <p>To run an application on an emulator or device, the application must be signed using debug or
+ release mode. You typically want to sign your application in debug mode when you develop and test
+ your application, because the build tools use a debug key with a known password so you do not have
+ to enter it every time you build. When you are ready to release the application to Google
+ Play, you must sign the application in release mode, using your own private key.</p>
+
+ <p>Fortunately, Eclipse or your Ant build script signs the application for you in debug mode
+ when you build your application. You can also easily setup Eclipse or your Ant build to sign your
+ application in release mode as well. For more information on signing applications, see <a href=
+ "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
+
+ <p>The following diagram depicts the components involved in building and running an application:</p>
+
+ <img src="{@docRoot}images/build-simplified.png" />
+
+ <h2 id="detailed-build">A Detailed Look at the Build Process</h2>
+
+ <p>The build process involves many tools and processes that generate intermediate files on the
+ way to producing an <code>.apk</code>. If you are developing in Eclipse, the complete build process is
+ automatically done periodically as you develop and save your code changes. If you are using other
+ IDEs, this build process is done every time you run the generated Ant build script for your
+ project. It is useful, however, to understand what is happening under the hood since much of the
+ tools and processes are masked from you. The following diagram depicts the different tools and
+ processes that are involved in a build:</p>
+
+ <img src="{@docRoot}images/build.png" />
+
+ <p>The general process for a typical build is outlined below:</p>
+
+ <ul>
+
+ <li>The Android Asset Packaging Tool (aapt) takes your application resource files, such as the
+ <code>AndroidManifest.xml</code> file and the XML files for your Activities, and compiles them. An <code>R.java</code> is
+ also produced so you can reference your resources from your Java code.</li>
+
+ <li>The aidl tool converts any <code>.aidl</code> interfaces that you have into Java interfaces.</li>
+
+ <li>All of your Java code, including the <code>R.java</code> and <code>.aidl</code> files, are compiled by the Java
+ compiler and .class files are output.</li>
+
+ <li>The dex tool converts the .class files to Dalvik byte code. Any 3rd party libraries and
+ .class files that you have included in your project are also converted into <code>.dex</code> files so that
+ they can be packaged into the final <code>.apk</code> file.</li>
+
+ <li>All non-compiled resources (such as images), compiled resources, and the .dex files are
+ sent to the apkbuilder tool to be packaged into an <code>.apk</code> file.</li>
+
+ <li>Once the <code>.apk</code> is built, it must be signed with either a debug or release key before it can
+ be installed to a device.</li>
+
+ <li>Finally, if the application is being signed in release mode, you must align the <code>.apk</code> with
+ the zipalign tool. Aligning the final <code>.apk</code> decreases memory usage when the application is
+ running on a device.</li>
+ </ul>
+