From 23110e49b3fee397967daa899061c24bde856f17 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 2 Sep 2009 10:25:09 -0700 Subject: [PATCH] docs only. add documentation about zipalign and new auto-signing procedures for Ant Change-Id: Ia66f5a7af58f77e52b3a5c26cb9972d317c2c42c --- docs/html/guide/developing/other-ide.jd | 121 +++++++-- docs/html/guide/developing/tools/index.jd | 5 + docs/html/guide/developing/tools/zipalign.jd | 65 +++++ docs/html/guide/guide_toc.cs | 1 + docs/html/guide/publishing/app-signing.jd | 246 ++++++++++++------- docs/html/guide/publishing/preparing.jd | 14 +- 6 files changed, 327 insertions(+), 125 deletions(-) create mode 100644 docs/html/guide/developing/tools/zipalign.jd diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd index 8cdf0b91d7b80..2080873eaf584 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.

navigate to the tools/ directory of your SDK and run:

 android create project \
---target <targetID> \
+--target <target_ID> \
+--name <your_project_name> \
 --path /path/to/your/project \
 --activity <your_activity_name> \
 --package <your_package_namespace>
@@ -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: android list targets.
+  
  • name 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.
    • 
   
  • path is the location of your project directory. If the directory does not exist,
   it will be created for you.
    • 
-  
  • activity is the name for your {@link android.app.Activity} class. This class file
+  
  • activity is the name for your default {@link android.app.Activity} class. This class file
   will be created for you inside 
-  <path_to_your_project>/src/<your_package_namespace_path>/.
    • 
+  <path_to_your_project>/src/<your_package_namespace_path>/.
+  This will also be used for your .apk filename unless you provide a the name.
   
  • package is the package namespace for your project, following the same rules as for
   packages in the Java programming language.
    • 
 
@@ -109,9 +113,10 @@ android create project \
 
     android create project \
 --target 1 \
---path ./myProject \
---activity MyActivity \
---package com.example.myproject
+--name MyAndroidApp \
+--path ./MyAndroidAppProject \
+--activity MyAndroidAppActivity \
+--package com.example.myandroid
 
    
 
 
    The tool generates the following files and directories:
    
@@ -123,7 +128,8 @@ android create project \
   
  • default.properties - Properties for the build system. Do not modify 
   this file.
    • 
   
  • build.properties - Customizable properties for the build system. You can edit this 
-  file to overried default build settings used by Ant.
    • 
+  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.
   
  • src/your/package/namespace/ActivityName.java - The Activity class 
   you specified during project creation.
    • 
   
  • bin/  - Output directory for the build script.
    • 
@@ -141,7 +147,7 @@ that you must use the Androi
 to the emulator (discussed later). So you need access between your project solution and 
 the tools/ folder.
    
 
-
    Note: You should refrain from moving the
+
    Caution: 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.)
    
@@ -153,14 +159,15 @@ work again.)
    
 a new project from existing code, use the
 android update project 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 --target option). The android tool will generate any files and 
+(with the --target option) and the project name (with the --name 
+option). The android 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.
    
 
 
    To update an existing Android project, open a command-line
 and navigate to the tools/ directory of your SDK. Now run:
    
 
    -android update project --target <targetID> --path path/to/your/project/
+android update project --name <project_name> --target <target_ID> --path path/to/your/project/
 
    
 
 
      
@@ -169,11 +176,13 @@ android update project --target <targetID> --path path/to/you
   like to build your project against. To see a list of available targets and their corresponding IDs, 
   execute: android list targets.
   
    • path is the location of your project directory.
      • 
+  
    • name is the name for the project. This is optional—if you're not 
+  changing the project name, you don't need this.
      • 
 
    
 
 
    Here's an example:
    
 
    -android update project --target 2 --path ./myProject
+android update project --name MyApp --target 2 --path ./MyAppProject
 
    
 
 
@@ -237,8 +246,9 @@ install JDK in a non-space directory, for example: c:\java\jdk1.6.0_02Building in debug mode
 
 
    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.
    
 
@@ -248,9 +258,9 @@ manually signing the application.
    
   
  • Open a command-line and navigate to the root of your project directory.
    • 
   
  • Use Ant to compile your project in debug mode:
     
    ant debug
    
-    
    This creates your Android application .apk file inside the project bin/
-    directory, named <your_DefaultActivity_name>-debug.apk. The file
-    is already signed with the debug key.
    
+    
    This creates your debug .apk file inside the project bin/
+    directory, named <your_project_name>-debug.apk. The file
+    is already signed with the debug key and has been aligned with {@code zipalign}.
    
   
    • 
 
 
@@ -267,23 +277,86 @@ about     Running Your Application.
    
 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.
    
 
-
    To build in release mode:
    
+
    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.
    
+
+
    Build unsigned
    
+
+
    If you build your application unsigned, then you will need to
+manually sign and align the package.
    
+
+
    To build an unsigned .apk in release mode:
    
 
 
      
   
    1. Open a command-line and navigate to the root of your project directory.
      2. 
   
    2. Use Ant to compile your project in release mode:
     
      ant release
      
-    
      This creates your Android application .apk file inside the project bin/
-    directory, named <your_DefaultActivity_name>.apk.
      
-    
      Note: The .apk file is unsigned at this point.
-    You can't install it on an emulator or device until you sign it with your private key.
      
   
      3. 
 
    
 
-
    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, 
+
    This creates your Android application .apk file inside the project bin/
+directory, named <your_project_name>-unsigned.apk.
    
+    
+
    Note: The .apk file is unsigned at this point 
+and can't be installed until signed with your private key.
    
+
+
    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 Signing Your Applications.
    
 
+
    When your .apk has been signed and aligned, it's ready to be distributed to end-users.
    
+
+
    Build signed and aligned
    
+
+
    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.
    
+
+
    Caution: Due to the way Ant handles input, the password that
+you enter during the build process will be visible. 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, buid unsigned and then continue 
+with Signing Your Applications.
    
+
+
    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:
    
+
+
    +key.store=/path/to/my.keystore
+key.alias=mykeystore
+
    
+
+
    Save your changes. Now you can build a signed .apk in release mode:
    
+
+
      
+  
    1. Open a command-line and navigate to the root of your project directory.
      2. 
+  
    2. Use Ant to compile your project in release mode:
+    
      ant release
      
+  
      3. 
+  
    3. When prompted, enter you keystore and alias passwords.
+    
      Caution: As described above, 
+    your password will be visible on the screen.
      
+  
      4. 
+
    
+
+
    This creates your Android application .apk file inside the project bin/
+directory, named <your_project_name>-release.apk.
+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.
    
+
+
+
    Once built and signed in release mode
    
+
 
    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 
 Running Your Application.
@@ -329,7 +402,7 @@ id:2
         you'll use this in the next step.
    
       
       
  • Create a new AVD using your selected deployment target:
-        
    android create avd --name <your_avd_name> --target <targetID>
    
+        
    android create avd --name <your_avd_name> --target <target_ID>
    
       
  • 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 2c9e45df3117a..91b430ff771a3 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. 
    
             
    A script that lets you manage AVDs and generate Ant build files that 
                         you can use to compile your Android applications. 
    
+                        
+  
    zipalign
    
+            
    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.
    
 
 
diff --git a/docs/html/guide/developing/tools/zipalign.jd b/docs/html/guide/developing/tools/zipalign.jd
new file mode 100644
index 0000000000000..6231798408d06
--- /dev/null
+++ b/docs/html/guide/developing/tools/zipalign.jd
@@ -0,0 +1,65 @@
+page.title=zipalign
+@jd:body
+
+
    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.
    
+
+
    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.
    
+
+
    Caution: zipalign must only be performed
+after 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.
    
+
+
    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.
    
+
+
    For more information about how to use zipalign when building your 
+application, please read Signing
+Your Application.
    
+
+
+
    Usage
    
+
+
    To align {@code infile.apk} and save it as {@code outfile.apk}:
    
+
+
    zipalign [-f] [-v] <alignment> infile.apk outfile.apk
    
+
+
    To confirm the alignment of {@code existing.apk}:
    
+
+
    zipalign -c -v <alignment> existing.apk
    
+
+
    The {@code <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.
    
+
+
    Flags:
    
+
+
      
+  
    • {@code -f} : overwrite existing outfile.zip
      • 
+  
    • {@code -v} : verbose output
      • 
+  
    • {@code -c} : confirm the alignment of the given file
      • 
+
    
+
+
+
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index a5dadbc25acd8..5abc872c96469 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -256,6 +256,7 @@
       		
  • Monkey
    • 
       		
  • sqlite3
    • 
       		
  • Traceview
    • 
+      		
  • zipalign
    •