docs only.

add documentation about zipalign and new auto-signing
procedures for Ant

Change-Id: Ia66f5a7af58f77e52b3a5c26cb9972d317c2c42c

6 files changed, 328 insertions, 126 deletions

diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd
index 8cdf0b9..2080873 100644
--- a/docs/html/guide/developing/other-ide.jd
+++ b/docs/html/guide/developing/other-ide.jd
@@ -85,7 +85,8 @@ command to generate all the necessary files and folders.</p>
 navigate to the <code>tools/</code> directory of your SDK and run:</p>
 <pre>
 android create project \
---target <em>&lt;targetID&gt;</em> \
+--target <em>&lt;target_ID&gt;</em> \
+--name <em>&lt;your_project_name&gt;</em> \
 --path <em>/path/to/your/project</em> \
 --activity <em>&lt;your_activity_name&gt;</em> \
 --package <em>&lt;your_package_namespace&gt;</em>
@@ -96,11 +97,14 @@ android create project \
   to an Android platform library (including any add-ons, such as Google APIs) that you would like to
   build your project against. To see a list of available targets and their corresponding IDs, 
   execute: <code>android list targets</code>.</li>
+  <li><code>name</code> is the name for your project. This is optional. If provided, this name will be used
+  for your .apk filename when you build your application.</li>
   <li><code>path</code> is the location of your project directory. If the directory does not exist,
   it will be created for you.</li>
-  <li><code>activity</code> is the name for your {@link android.app.Activity} class. This class file
+  <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This class file
   will be created for you inside 
-  <code><em>&lt;path_to_your_project&gt;</em>/src/<em>&lt;your_package_namespace_path&gt;</em>/</code>.</li>
+  <code><em>&lt;path_to_your_project&gt;</em>/src/<em>&lt;your_package_namespace_path&gt;</em>/</code>.
+  This will also be used for your .apk filename unless you provide a the <code>name</code>.</li>
   <li><code>package</code> is the package namespace for your project, following the same rules as for
   packages in the Java programming language.</li>
 </ul>
@@ -109,9 +113,10 @@ android create project \
 <pre>
 android create project \
 --target 1 \
---path ./myProject \
---activity MyActivity \
---package com.example.myproject
+--name MyAndroidApp \
+--path ./MyAndroidAppProject \
+--activity MyAndroidAppActivity \
+--package com.example.myandroid
 </pre>
 
 <p>The tool generates the following files and directories:</p>
@@ -123,7 +128,8 @@ android create project \
   <li><code>default.properties</code> - Properties for the build system. <em>Do not modify 
   this file</em>.</li>
   <li><code>build.properties</code> - Customizable properties for the build system. You can edit this 
-  file to overried default build settings used by Ant.</li>
+  file to override default build settings used by Ant and provide a pointer to your keystore and key alias
+  so that the build tools can sign your application when built in release mode.</li>
   <li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class 
   you specified during project creation.</li>
   <li><code>bin/</code>  - Output directory for the build script.</li>
@@ -141,7 +147,7 @@ that you must use the <a href="{@docRoot}guide/developing/tools/adb.html">Androi
 to the emulator (discussed later). So you need access between your project solution and 
 the <code>tools/</code> folder.</p>
 
-<p class="warning"><strong>Note:</strong> You should refrain from moving the
+<p class="caution"><strong>Caution:</strong> You should refrain from moving the
 location of the SDK directory, because this will break the build scripts. (They
 will need to be manually updated to reflect the new SDK location before they will
 work again.)</p>
@@ -153,14 +159,15 @@ work again.)</p>
 a new project from existing code, use the
 <code>android update project</code> command to update the project to the new development
 environment. You can also use this command to revise the build target of an existing project
-(with the <code>--target</code> option). The <code>android</code> tool will generate any files and 
+(with the <code>--target</code> option) and the project name (with the <code>--name</code> 
+option). The <code>android</code> tool will generate any files and 
 folders (listed in the previous section) that are either missing or need to be updated, 
 as needed for the Android project.</p>
 
 <p>To update an existing Android project, open a command-line
 and navigate to the <code>tools/</code> directory of your SDK. Now run:</p>
 <pre>
-android update project --target <em>&lt;targetID&gt;</em> --path <em>path/to/your/project/</em>
+android update project --name <em>&lt;project_name&gt;</em> --target <em>&lt;target_ID&gt;</em> --path <em>path/to/your/project/</em>
 </pre>
 
 <ul>
@@ -169,11 +176,13 @@ android update project --target <em>&lt;targetID&gt;</em> --path <em>path/to/you
   like to build your project against. To see a list of available targets and their corresponding IDs, 
   execute: <code>android list targets</code>.</li>
   <li><code>path</code> is the location of your project directory.</li>
+  <li><code>name</code> is the name for the project. This is optional&mdash;if you're not 
+  changing the project name, you don't need this.</li>
 </ul>
 
 <p>Here's an example:</p>
 <pre>
-android update project --target 2 --path ./myProject
+android update project --name MyApp --target 2 --path ./MyAppProject
 </pre>
 
 
@@ -237,8 +246,9 @@ install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</co
 <h3 id="DebugMode">Building in debug mode</h3>
 
 <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. However, you can (and should) also test your
+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}. However, you can (and should) also test your
 application in release mode. Debug mode simply allows you to run your application without
 manually signing the application.</p>
 
@@ -248,9 +258,9 @@ manually signing the application.</p>
   <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 Android application .apk file inside the project <code>bin/</code>
-    directory, named <code><em>&lt;your_DefaultActivity_name&gt;</em>-debug.apk</code>. The file
-    is already signed with the debug key.</p>
+    <p>This creates your debug .apk file inside the project <code>bin/</code>
+    directory, named <code><em>&lt;your_project_name&gt;</em>-debug.apk</code>. The file
+    is already signed with the debug key and has been aligned with {@code zipalign}.</p>
   </li>
 </ol>
 
@@ -267,23 +277,86 @@ about <a href="#Running">Running Your Application</a>.</p>
 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>To build in release mode:</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>
+
+<h4 id="ManualReleaseMode">Build unsigned</h4>
+
+<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>
-    <p>This creates your Android application .apk file inside the project <code>bin/</code>
-    directory, named <code><em>&lt;your_DefaultActivity_name&gt;</em>.apk</code>.</p>
-    <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point.
-    You can't install it on an emulator or device until you sign it with your private key.</p>
   </li>
 </ol>
 
-<p>Because release mode builds your application unsigned, your next step is to sign
-it with your private key, in order to distribute it to end-users. To complete this procedure, 
+<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 .apk has been signed and aligned, it's ready to be distributed to end-users.</p>
+
+<h4 id="AutoReleaseMode">Build signed and aligned</h4>
+
+<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">buid 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>
+
+
+<h4>Once built and signed in release mode</h4>
+
 <p>Once you have signed your application with a private key, you can install it on an 
 emulator or device as discussed in the following section about 
 <a href="#Running">Running Your Application</a>.
@@ -329,7 +402,7 @@ id:2
         you'll use this in the next step.</p>
       </li>
       <li>Create a new AVD using your selected deployment target:
-        <pre>android create avd --name <em>&lt;your_avd_name&gt;</em> --target <em>&lt;targetID&gt;</em></pre>
+        <pre>android create avd --name <em>&lt;your_avd_name&gt;</em> --target <em>&lt;target_ID&gt;</em></pre>
       <li>Next, you'll be asked whether you'd like to create a custom hardware profile.
       If you respond "yes," you'll be presented with a series of prompts to define various aspects of the
       device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise,
diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd
index 2c9e45d..91b430f 100644
--- a/docs/html/guide/developing/tools/index.jd
+++ b/docs/html/guide/developing/tools/index.jd
@@ -89,5 +89,10 @@ applications on the emulator. </p>
             <dd>A script that lets you manage AVDs and generate <a
                         href="http://ant.apache.org/" title="Ant">Ant</a> build files that 
                         you can use to compile your Android applications. </dd>
+                        
+  <dt><a  href="zipalign.html">zipalign</a></dt>
+            <dd>An important .apk optimization tool. This tool ensures that all uncompressed data starts
+            with a particular alignment relative to the start of the file. This should always be used
+            to align .apk files after they have been signed.</dd>
 </dl>
 
diff --git a/docs/html/guide/developing/tools/zipalign.jd b/docs/html/guide/developing/tools/zipalign.jd
new file mode 100644
index 0000000..6231798
--- /dev/null
+++ b/docs/html/guide/developing/tools/zipalign.jd
@@ -0,0 +1,65 @@
+page.title=zipalign
+@jd:body
+
+<p>zipalign is an archive alignment tool that provides important
+optimization to Android application (.apk) files. 
+The purpose is to ensure that all uncompressed data starts
+with a particular alignment relative to the start of the file.  Specifically,
+it causes all uncompressed data within the .apk, such as images or raw files,
+to be aligned on 4-byte boundaries. This
+allows all portions to be accessed directly with {@code mmap()} even if they
+contain binary data with alignment restrictions. 
+The benefit is a reduction in the amount of RAM consumed 
+when running the application.</p>
+
+<p>This tool should always be used to align your .apk file before 
+distributing it to end-users. The Android build tools can handle
+this for you. When using Eclipse with the ADT plugin, the Export Wizard
+will automatically zipalign your .apk after it signs it with your private key. 
+The build scripts used
+when compiling your application with Ant will also zipalign your .apk,
+as long as you have provided the path to your keystore and the key alias in
+your project {@code build.properties} file, so that the build tools 
+can sign the package first.</p>
+
+<p class="caution"><strong>Caution:</strong> zipalign must only be performed
+<strong>after</strong> the .apk file has been signed with your private key.
+If you perform zipalign before signing, then the signing procedure will undo
+the alignment. Also, do not make alterations to the aligned package.
+Alterations to the archive, such as renaming or deleting entries, will
+potentially disrupt the alignment of the modified entry and all later
+entries. And any files added to an "aligned" archive will not be aligned.</p>
+
+<p>The adjustment is made by altering the size of
+the "extra" field in the zip Local File Header sections.  Existing data
+in the "extra" fields may be altered by this process.</p>
+
+<p>For more information about how to use zipalign when building your 
+application, please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing
+Your Application</a>.</p>
+
+
+<h3>Usage</h3>
+
+<p>To align {@code infile.apk} and save it as {@code outfile.apk}:</p>
+
+<pre>zipalign [-f] [-v] &lt;alignment> infile.apk outfile.apk</pre>
+
+<p>To confirm the alignment of {@code existing.apk}:</p>
+
+<pre>zipalign -c -v &lt;alignment> existing.apk</pre>
+
+<p>The {@code &lt;alignment>} is an integer that defines the byte-alignment boundaries. 
+This must always be 4 (which provides 32-bit alignment) or else it effectively 
+does nothing.</p>
+
+<p>Flags:</p>
+
+<ul>
+  <li>{@code -f} : overwrite existing outfile.zip</li>
+  <li>{@code -v} : verbose output</li>
+  <li>{@code -c} : confirm the alignment of the given file</li>
+</ul>
+
+
+
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index a5dadbc..5abc872 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -256,6 +256,7 @@
       		<li><a href="<?cs var:toroot ?>guide/developing/tools/monkey.html">Monkey</a></li>
       		<li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html#sqlite">sqlite3</a></li>
       		<li><a href="<?cs var:toroot ?>guide/developing/tools/traceview.html" >Traceview</a></li>
+      		<li><a href="<?cs var:toroot ?>guide/developing/tools/zipalign.html" >zipalign</a></li>
     	  </ul>
   	  </li>
   <!--<li><a href="<?cs var:toroot ?>guide/developing/instrumentation/index.html">Instrumentation</a></li>
diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd
index a16c910..f0febc0 100644
--- a/docs/html/guide/publishing/app-signing.jd
+++ b/docs/html/guide/publishing/app-signing.jd
@@ -22,10 +22,11 @@ page.title=Signing Your Applications
 <li><a href="#debugmode">Signing in Debug Mode</a></li>
 <li><a href="#releasemode">Signing for Public Release</a>
     <ol>
-    <li><a href="#releasecompile">Compiling for release</a></li>
-    <li><a href="#cert">Obtaining a suitable private key</a></li>
-    <li><a href="#signapp">Signing your application</a></li>
-    <li><a href="#ExportWizard">Compiling and signing with Eclipse ADT</a></li>
+    <li><a href="#cert">Obtain a suitable private key</a></li>
+    <li><a href="#releasecompile">Compile the application in release mode</a></li>
+    <li><a href="#signapp">Sign your application with your private key</a></li>
+    <li><a href="#align">Align the final APK package</a></li>
+    <li><a href="#ExportWizard">Compile and sign with Eclipse ADT</a></li>
     </ol>
 </li>
 <li><a href="#secure-key">Securing Your Private Key</a></li>
@@ -71,6 +72,7 @@ application's signer certificate expires after the application is installed, the
 will continue to function normally.</li>
   <li>You can use standard tools &mdash; Keytool and Jarsigner &mdash; to generate keys and 
 sign your application .apk files.</li>
+  <li>Once you have signed the application, use the <code>zipalign</code> tool to optimize the final APK package.</li>
 </ul>
 
 <p>The Android system will not install or run an application that is not signed appropriately. This 
@@ -107,6 +109,9 @@ There are two ways to do this:
 </li>
 </ul>
 
+<p>Once your application is signed, don't forget to run {@code zipalign} on the APK
+for additional optimization.</p>
+
 <h2 id="strategies">Signing Strategies</h2>
 
 <p>Some aspects of application signing may affect how you approach the development
@@ -171,16 +176,16 @@ use a <a href="#cert">suitable certificate</a> to sign your applications. </p>
 
 <h2 id="setup">Basic Setup for Signing</h2>
 
-<p>To support the generation of a keystore and debug key, you should first make sure that 
+<p>Before you begin, you should make sure that 
 Keytool is available to the SDK build 
-tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure 
-that your JAVA_HOME environment variable is set and that it references a suitable JDK. 
-Alternatively, you can add the JDK version of Keytool to your PATH variable.</p>
+tools. In most cases, you can tell the SDK build tools how to find Keytool by setting
+your <code>JAVA_HOME</code> environment variable to references a suitable JDK. 
+Alternatively, you can add the JDK version of Keytool to your <code>PATH</code> variable.</p>
 
 <p>If you are developing on a version of Linux that originally came with GNU Compiler for 
 Java, make sure that the system is using the JDK version of Keytool, rather than the gcj 
-version. If Keytool is already in your PATH, it might be pointing to a symlink at 
-<code>/usr/bin/keytool</code>. In this case, check the symlink target to make sure that it points 
+version. If Keytool is already in your <code>PATH</code>, it might be pointing to a symlink at 
+<code>/usr/bin/keytool</code>. In this case, check the symlink target to be sure it points 
 to the Keytool in the JDK.</p>
 
 <p>If you will release your application to the public, you will also need to have
@@ -191,46 +196,50 @@ in the JDK. </p>
 
 <p>The Android build tools provide a debug signing mode that makes it easier for you 
 to develop and debug your application, while still meeting the Android system
-requirement for signing your .apk when it is installed in the emulator or a device. 
-When you use debug mode, the SDK tools invoke Keytool to create a debug 
-keystore and key.</p>
+requirement for signing your .apk.
+When using debug mode to build your app, the SDK tools invoke Keytool to automatically create
+a debug keystore and key. This debug key is then used to automatically sign the .apk, so
+you do not need to sign the package with your own key.</p>
 
-<p>The SDK tools create the debug keystore/key with predetermined names/passwords;</p>
+<p>The SDK tools create the debug keystore/key with predetermined names/passwords:</p>
 <ul>
-<li>Keystore name &ndash; "debug.keystore"</li>
-<li>Keystore password &ndash; "android"</li>
-<li>Key alias &ndash; "androiddebugkey"</li>
-<li>Key password &ndash; "android"</li>
-<li>CN &ndash; "CN=Android Debug,O=Android,C=US"</li>
+<li>Keystore name: "debug.keystore"</li>
+<li>Keystore password: "android"</li>
+<li>Key alias: "androiddebugkey"</li>
+<li>Key password: "android"</li>
+<li>CN: "CN=Android Debug,O=Android,C=US"</li>
 </ul></p>
 
 <p>If necessary, you can change the location/name of the debug keystore/key or
-supply a custom debug keystore/key to use. In Eclipse/ADT, you can use
-<strong>Windows</strong> &gt; <strong>Prefs</strong> &gt;
-<strong>Android</strong> &gt; <strong>Build</strong>. However, any custom debug
+supply a custom debug keystore/key to use. However, any custom debug
 keystore/key must use the same keystore/key names and passwords as the default
-debug key (as described above).</p>
+debug key (as described above). (To do so in Eclipse/ADT, go to
+<strong>Windows</strong> &gt; <strong>Preferences</strong> &gt;
+<strong>Android</strong> &gt; <strong>Build</strong>.) </p>
 
-<p class="note"><strong>Note:</strong> You <em>cannot</em> release your application 
+<p class="caution"><strong>Caution:</strong> You <em>cannot</em> release your application 
 to the public when signed with the debug certificate.</p>
 
 <h3>Eclipse Users</h3>
 
-<p>If you are developing in Eclipse/ADT and have set up Keytool as described
-above, signing in debug mode is enabled by default. When you run or debug your
-application, ADT signs the .apk with the debug certificate and installs it on 
-the emulator. No specific action on your part is needed, provided ADT has 
-access to Keytool.</p>
+<p>If you are developing in Eclipse/ADT (and have set up Keytool as described above in 
+<a href="#setup">Basic Setup for Signing</a>),
+signing in debug mode is enabled by default. When you run or debug your
+application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the 
+package, then installs it on 
+the selected emulator or connected device. No specific action on your part is needed, 
+provided ADT has access to Keytool.</p>
 
 <h3>Ant Users</h3>
 
-<p>If you use Ant to build your .apk files, debug signing mode 
-is enabled by using the <code>debug</code> option, assuming that you are using a 
-<code>build.xml</code> file generated by the 
-<code>android</code> tool. When you run <code>ant debug</code> to 
+<p>If you are using Ant to build your .apk files, debug signing mode 
+is enabled by using the <code>debug</code> option with the <code>ant</code> command
+(assuming that you are using a <code>build.xml</code> file generated by the
+<code>android</code> tool). When you run <code>ant debug</code> to 
 compile your app, the build script generates a keystore/key and signs the .apk for you. 
+The script then also aligns the .apk with the <code>zipalign</code> tool.
 No other action on your part is needed. Read 
-<a href="{@docRoot}guide/developing/other-ide.html#DebugMode">Developing In Other IDEs: Building 
+<a href="{@docRoot}guide/developing/other-ide.html#DebugMode">Developing In Other IDEs: Building
 in debug mode</a> for more information.</p>
 
 
@@ -268,51 +277,20 @@ certificate</a>. </p>
 
 <p>When your application is ready for release to other users, you must:</p>
 <ol>
-  <li>Compile the application in release mode</li>
-  <li>Obtain a suitable private key</li>
-  <li>Sign the application with your private key</li>
+  <li><a href="#cert">Obtain a suitable private key</a></li>
+  <li><a href="#releasecompile">Compile the application in release mode</li>
+  <li><a href="#signapp">Sign your application with your private key</a></li>
+  <li><a href="#align">Align the final APK package</a></li>
 </ol>
 
-<p>The sections below provide information about how to perform these steps.</p>
-
-<p>If you use Eclipse with the ADT plugin, you can instead use the Export Wizard
-to compile and sign an .apk with your private key. The Export Wizard even allows you to 
-generate a new keystore and private key in the process. Skip to
-<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>
-
-
-<h3 id="releasecompile">Compiling for release</h3>
-
-<p>To prepare your application for release, you must first compile it in release mode. 
-In release mode, the Android build tools compile your application as usual, 
-but without signing it with the debug key.</p>
-
-<p class="warning"><strong>Note:</strong>
-You can not release your application unsigned, or signed with the debug key.</p>
+<p>If you are developing in Eclipse with the ADT plugin, you can use the Export Wizard
+to perform the compile, sign, and align procedures. The Export Wizard even allows you to 
+generate a new keystore and private key in the process. So if you use Eclipse, you can 
+skip to <a href="#ExportWizard">Compile and sign with Eclipse ADT</a>.</p>
 
-<h4>Eclipse users</h4>
 
-<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package 
-Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application 
-Package</strong>. Then simply specify the file location for the unsigned .apk.
-(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open 
-the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p>
-
-<p>You can also combine the compiling and signing steps with the Export Wizard. See 
-<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>
 
-<h4>Ant users</h4>
-
-<p>If you are using Ant, all you need to do is specify the build target 
-"release" in the Ant command. For example, if you are running Ant from the 
-directory containing your build.xml file, the command would look like this:</p>
-
-<pre>$ ant release</pre>
-
-<p>The build script compiles the application .apk without signing it.</p>
-
-
-<h3 id="cert">Obtaining a Suitable Private Key</h3>
+<h3 id="cert">1. Obtain a suitable private key</h3>
 
 <p>In preparation for signing your application, you must first ensure that 
 you have a suitable private key with which to sign. A suitable private 
@@ -339,7 +317,8 @@ in <a href="#setup">Basic Setup</a>.</p>
 command and pass any of the options listed below (and any others, as
 needed). </p>
 
-<p class="warning"><strong>Note:</strong> Before you run Keytool, make sure to read 
+<p class="warning"><strong>Warning:</strong> Keep your private key secure. 
+Before you run Keytool, make sure to read 
 <a href="#secure-key">Securing Your Private Key</a> for a discussion of how to keep
 your key secure and why doing so is critically important to you and to users. In
 particular, when you are generating your key, you should select strong passwords
@@ -395,7 +374,6 @@ way, your password is not stored in your shell history.</p></td>
 </tr>
 </table>
 
-
 <p>Here's an example of a Keytool command that generates a private key:</p>
 
 <pre>$ keytool -genkey -v -keystore my-release-key.keystore 
@@ -415,9 +393,57 @@ href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security">
 http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>
 
 
-<h3 id="signapp">Signing your application</h3>
 
-<p>When you are ready to actually sign your .apk for release, you can do so
+<h3 id="releasecompile">2. Compile the application in release mode</h3>
+
+<p>In order to release your application to users, you must compile it in release mode. 
+In release mode, the compiled application is not signed by default and you will need
+to sign it with your private key.</p>
+
+<p class="caution"><strong>Caution:</strong>
+You can not release your application unsigned, or signed with the debug key.</p>
+
+<h4>With Eclipse</h4>
+
+<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package 
+Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application 
+Package</strong>. Then specify the file location for the unsigned .apk.
+(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open 
+the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p>
+
+<p>Note that you can combine the compiling and signing steps with the Export Wizard. See 
+<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>
+
+<h4>With Ant</h4>
+
+<p>If you are using Ant, you can enable release mode by using the <code>release</code> option
+with the <code>ant</code> command. For example, if you are running Ant from the 
+directory containing your {@code build.xml} file, the command would look like this:</p>
+
+<pre>ant release</pre>
+
+<p>By default, the build script compiles the application .apk without signing it. The output file
+in your project {@code bin/} will be <code><em>&lt;your_project_name></em>-unsigned.apk</code>.
+Because the application .apk is still unsigned, you must manually sign it with your private
+key and then align it using {@code zipalign}.</p>
+
+<p>However, the Ant build script can also perform the signing
+and aligning for you, if you have provided the path to your keystore and the name of
+your key alias in the project's {@code build.properties} file. With this information provided,
+the build script will prompt you for your keystore and alias password when you perform
+<code>ant release</code>, it will sign the package and then align it. The final output
+file in {@code bin/} will instead be 
+<code><em>&lt;your_project_name></em>-release.apk</code>. With these steps
+automated for you, you're able to skip the manual procedures below (steps 3 and 4).
+To learn how to specify your keystore and alias in the {@code build.properties} file,
+see <a href="{@docRoot}guide/developing/other-ide.html#ReleaseMode">Developing In Other
+IDEs: Building in release mode</a>.</p>
+
+
+
+<h3 id="signapp">3. Sign your application with your private key</h3>
+
+<p>When you have an application package that is ready to be signed, you can do sign it
 using the Jarsigner tool. Make sure that you have Jarsigner available on your
 machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that
 the keystore containing your private key is  available.</p>
@@ -492,29 +518,63 @@ key.</p>
 http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>
 
 
-<h3 id="ExportWizard">Compiling and signing with Eclipse ADT</h3>
+<h3 id="align">4. Align the final APK package</h3>
 
-<p>When using Eclipse with ADT, you can use the Export Wizard to
+<p>Once you have signed the .apk with your private key, run <code>zipalign</code> on the file.
+This tool ensures that all uncompressed data starts with a particular byte alignment,
+relative to the start of the file. Ensuring alignment at 4-byte boundaries provides
+a performance optimization when installed on a device. When aligned, the Android
+system is able to read files with {@code mmap()}, even if
+they contain binary data with alignment restrictions, rather than copying all
+of the data from the package. The benefit is a reduction in the amount of
+RAM consumed by the running application.</p>
+
+<p>The <code>zipalign</code> tool is provided with the Android SDK, inside the 
+<code>tools/</code> directory. To align your signed .apk, execute:</p>
+
+<pre>zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre>
+
+<p>The {@code -v} flag turns on verbose output (optional). {@code 4} is the
+byte-alignment (don't use anything other than 4). The first file argument is
+your signed .apk (the input) and the second file is the destination .apk file (the output). 
+If you're overriding an existing .apk, add the {@code -f} flag.</p>
+
+<p class="caution"><strong>Caution:</strong> Your input .apk must be signed with your
+private key <strong>before</strong> you optimize the package with {@code zipalign}.
+If you sign it after using {@code zipalign}, it will undo the alignment.</p>
+
+<p>For more information, read about the 
+<a href="{@docRoot}guide/developing/tools/zipalign.html">zipalign</a> tool.
+
+
+<h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3>
+
+<p>If you are using Eclipse with the ADT plugin, you can use the Export Wizard to
 export a <em>signed</em> .apk (and even create a new keystore,
 if necessary). The Export Wizard performs all the interaction with
-the Keytool and Jarsigner for you, which allows you to perform signing via a
-graphical interface instead of the command-line.
+the Keytool and Jarsigner for you, which allows you to sign the package using a GUI
+instead of performing the manual procedures to compile, sign,
+and align, as discussed above. Once the wizard has compiled and signed your package,
+it will also perfom package alignment with {@code zipalign}.
 Because the Export Wizard uses both Keytool and Jarsigner, you should
 ensure that they are accessible on your computer, as described above
 in the <a href=#setup">Basic Setup for Signing</a>.</p>
 
-<p>To create a signed .apk, right-click the project in the Package 
-Explorer and select <strong>Android Tools > Export Signed Application Package</strong>.
-(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open 
-the <em>Overview</em> tab, and click <strong>Use the Export Wizard</strong>.)
-The window that appears will display any errors found while 
-attempting to export your application. If no errors are found, continue with the
-Export Wizard, which will guide you through the process of signing your application,
-including steps for selecting the private key with which to sign the .apk,
-or creating a new keystore and private key.</p>
-
-<p>When you complete the Export Wizard, you'll
-have a signed .apk that's ready for distribution.</p>
+<p>To create a signed and aligned .apk in Eclipse:</p>
+
+<ol>
+  <li>Select the project in the Package 
+Explorer and select <strong>File > Export</strong>.</li>
+  <li>Open the Android folder, select Export Android Application, 
+  and click <strong>Next</strong>.
+  <p>The Export Android Application wizard now starts, which will 
+  guide you through the process of signing your application,
+  including steps for selecting the private key with which to sign the .apk
+  (or creating a new keystore and private key).</p>
+  <li>Complete the Export Wizard and your application will be compiled, 
+  signed, aligned, and ready for distribution.</li>
+</ol>
+
 
 
 <h2 id="secure-key">Securing Your Private Key</h2>
diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd
index b4eaea3..5357166 100644
--- a/docs/html/guide/publishing/preparing.jd
+++ b/docs/html/guide/publishing/preparing.jd
@@ -220,22 +220,20 @@ elements, any MapView elements referencing the old Key will not have permission
 to download Maps data. </li>
 </ol>
 
-<p>For more information about signing and your private key, see <a
-href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
-
-
 <h2 id="compile">Compile your application</h2>
 
 <p>When you've prepared your application as described in the previous sections,
-you can compile your application for release. </p>
+you can compile your application for release.</p>
+
 
 <h2 id="post-compile">After compiling your application</h2>
 
 <h3 id="signapp">8. Sign your application</h3>
 
-<p>Sign your application using your private key. Signing your application
-correctly is critically important. Please see 
-<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your
+<p>Sign your application using your private key and then
+align it with the {@code zipalign} tool. Signing your application
+correctly is critically important. Please see
+<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your 
 Applications</a> for complete information. </p>
 
 <h3 id="testapp">9. Test your compiled and signed application</h3>