AI 147335: am: CL 147334 am: CL 147332 Miscellaneous doc changes for cupcake SDK

  Original author: ddougherty
  Merged from: //branches/cupcake/...
  Original author: android-build

Automated import of CL 147335

2 files changed, 8 insertions, 432 deletions

diff --git a/docs/html/guide/developing/app-signing.jd b/docs/html/guide/developing/app-signing.jd
deleted file mode 100644
index 582dfb2..0000000
--- a/docs/html/guide/developing/app-signing.jd
+++ /dev/null
@@ -1,428 +0,0 @@
-page.title=Signing Your Applications
-@jd:body
-
-<p>The Android system requires that all installed applications be digitally
-signed with a certificate whose private key is held by the application's
-developer. The system uses the certificate as a means of identifying the author of
-an application and establishing trust relationships between applications, rather
-than for controlling which applications the user can install. The certificate
-does not need to be signed by a certificate authority: it is perfectly
-allowable, and typical, for Android applications to use self-signed
-certificates.</p>
-
-<p>The important points to understand about signing Android applications are:</p>
-
-<ul>
-  <li>All applications <em>must</em> be signed. The system will not install an application 
-that is not signed.</li>
-  <li>You can use self-signed certificates to sign your applications. No certificate authority 
-is needed.</li>
-  <li>When you are ready to publish your application, you must sign it with a suitable private 
-key. You can not publish an application that is signed with the default key generated 
-by the SDK tools. 
-  </li>
-  <li>The system tests a signer certificate's expiration date only at install time. If an 
-application's signer certificate expires after the application is installed, the application 
-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>
-</ul>
-
-<p>The Android system will not install or run an application that is not signed appropriately. This 
-applies wherever the Android system is run, whether on an actual device or on the emulator. 
-For this reason, you must set up signing for your application before you will be able to 
-run or debug it on an emulator or device.</p>
-
-<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin 
-for Eclipse and the Ant build tool offer two signing modes &mdash; debug mode and release mode. 
-
-<ul>
-<li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create 
-a keystore and key with a known alias and password. At each compilation, the tools then use 
-the debug key to sign the application .apk file. Because the password is known, the tools 
-don't need to prompt you for the keystore/key password each time you compile.</li>
-
-<li>When your application is ready for release, you compile it in release signing mode. 
-In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign
-the .apk manually &mdash; <span style="color:red">with your private key</span> &mdash; 
-using Jarsigner (or similar tool). If you do not have a suitable private key already, 
-you can run Keytool manually to generate your own keystore/key and then sign your 
-application with Jarsigner.</li>
-</ul>
-
-<h2>Signing Strategies</h2>
-
-<p>Some aspects of application signing may affect how you approach the development
-of your application, especially if you are planning to release multiple
-applications. </p>
-
-<p>In general, the recommended strategy for all developers is to sign
-all of your applications with the same certificate, throughout the expected
-lifespan of your applications. There are several reasons why you should do so: </p>
-
-<ul>
-<li>Application upgrade &mdash; As you release upgrades to your
-application, you will want to sign the upgrades with the same certificate, if you
-want users to upgrade seamlessly to the new version. When the system is 
-installing an update to an application, if any of the certificates in the 
-new version match any of the certificates in the old version, then the 
-system allows the update. If you sign the version without using a matching
-certificate, you will also need to assign a different package name to the 
-application &mdash; in this case, the user installs the new version as a 
-completely new application. 
-
-<li>Application modularity &mdash; The Android system allows applications that
-are signed by the same certificate to run in the same process, if the
-applications so request, so that the system treats them as a single application.
-In this way you can deploy your application in modules, and users can update
-each of the modules independently if needed.</li>
-
-<li>Code/data sharing through permissions &mdash; The Android system provides
-signature-based permissions enforcement, so that an application can expose
-functionality to another application that is signed with a specified
-certificate. By signing multiple applications with the same certificate and
-using signature-based permissions checks, your applications can share code and
-data in a secure manner. </li>
-
-</li>
-
-</ul>
-
-<p>Another important consideration in determining your signing strategy is 
-how to set the validity period of the key that you will use to sign your 
-applications.</p>
-
-<ul>
-<li>If you plan to support upgrades for a single application, you should ensure 
-that your key has a validity period that exceeds the expected lifespan of
-that application. A validity period of 25 years or more is recommended. 
-When your key's validity period expires, users will no longer be
-able to seamlessly upgrade to new versions of your application.</li>
-
-<li>If you will sign multiple distinct applications with the same key, 
-you should ensure that your key's validity period exceeds the expected 
-lifespan of <em>all versions of all of the applications</em>, including 
-dependent applications that may be added to the suite in the future. </li>
-
-<li>If you plan to publish your application(s) on Android Market, the
-key you use to sign the application(s) must have a validity period 
-ending after 22 October 2033. The Market server enforces this requirement
-to ensure that users can seamlessly upgrade Market applications when
-new versions are available. </li>
-</ul>
-
-<p>As you design your application, keep these points in mind and make sure to
-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 
-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>
-
-<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 
-/usr/bin/keytool. In this case, check the symlink target to make sure that 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
-the Jarsigner tool available on your machine. Both Jarsigner and Keytool are included
-in the JDK. </p>
-
-<h2>Signing in Debug Mode</h2>
-
-<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. </p>
-
-<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 for you and installs it on the emulator. No
-specific action on your part is needed, provided ADT has access to Keytool.</p>
-
-<p>If you use Ant to build your .apk files, debug signing mode 
-is enabled by default, assuming that you are using a build.xml file generated by the 
-activitycreator tool included in the latest SDK. When you run Ant against build.xml to 
-compile your app, the build script generates a keystore/key and signs the .apk for you. 
-No specific action on your part is needed.</p>
-
-<p>Note that you can not release your application to the public if it is signed only with
-the debug key. </p>
-
-<h2>Signing for Public Release</h2>
-
-<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, and then</li>
-<li>Sign the application with your private key</li>
-<li>Secure your private key</li>
-</ol>
-
-<p>The sections below provide information about these steps. </p>
-
-<h3>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>If you are developing in Eclipse/ADT, right-click the project in the Package 
-pane and select <strong>Android Tools</strong> > <strong>Export Application 
-Package</strong>. You can then specify the file location for the unsigned .apk. 
-Alternatively, you can follow the "Exporting the unsigned .apk" 
-link in the Manifest Editor overview page. </p>
-
-<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>Note that you can not release your application unsigned, or signed with the debug key.</p>
-
-<h3 id="cert">Obtaining 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 
-key is one that:</p>
-
-<ul>
-<li>Is in your possession</li>
-<li>Represents the personal, corporate, or organizational entity to be identified 
-with the application</li>
-<li>Has a validity period that exceeds the expected lifespan of the application
-or application suite. A validity period of more than 25 years is recommended. 
-<p>If you plan to publish your application(s) on Android Market, note that a 
-validity period ending after 22 October 2033 is a requirement. You can not upload an
-application if it is signed with a key whose validity expires before that date. 
-</p></li>
-<li>Is not the debug key generated by the Android SDK tools. </li>
-</ul>
-
-<p>The key may be self-signed. If you do not have a suitable key, you must 
-generate one using Keytool. Make sure that you have Keytool available, as described
-in <a href="#setup">Basic Setup</a>.</p>
-
-<p>To generate a self-signed key with Keytool, use the <code>keytool</code>
-command and pass any of the options listed below (and any others, as
-needed). </p>
-
-<p class="warning">Before you run Keytool, make sure to read <a
-href="#secure-key">Securing Your 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 for both the keystore and key.</p>
-
-<table>
-<tr>
-<th>Keytool Option</th>
-<th>Description</th>
-</tr>
-<tr>
-<td><code>-genkey</code></td><td>Generate a key pair (public and private
-keys)</td>
-</tr>
-<tr>
-<td><code>-v</code></td><td>Enable verbose output.</td>
-</tr>
-<tr>
-<td><code>-keystore&nbsp;&lt;keystore-name&gt;.keystore</code></td><td>A name
-for the keystore containing the private key.</td>
-</tr>
-<tr>
-<td><code>-storepass &lt;password&gt;</code></td><td><p>A password for the
-keystore.</p><p>As a security precaution, do not include this option 
-in your command line unless you are working at a secure computer.
-If not supplied, Keytool prompts you to enter the password. In this 
-way, your password is not stored in your shell history.</p></td>
-</tr>
-<tr>
-<td><code>-alias &lt;alias_name&gt;</code></td><td>An alias for the key.</td>
-</tr>
-<tr>
-<td><code>-keyalg &lt;alg&gt;</code></td><td>The encryption algorithm to use 
-when generating the key.</td>
-</tr>
-<tr>
-<td><code>-dname &lt;name&gt;</code></td><td><p>A Distinguished Name that describes
-who created the key. The value is used as the issuer and subject fields in the
-self-signed certificate. </p><p>Note that you do not need to specify this option
-in the command line. If not supplied, Jarsigner prompts you to enter each 
-of the Distinguished Name fields (CN, OU, and so on).</p></td>
-</tr>
-<tr>
-<td><code>-validity &lt;valdays&gt;</code></td><td><p>The validity period for the
-key, in days. </p><p><strong>Note:</strong> A value of 9500 or greater is recommended.</p></td>
-</tr>
-<tr>
-<td><code>-keypass &lt;password&gt;</code></td><td><p>The password for the key.</p>
-<p>As a security precaution, do not include this option 
-in your command line unless you are working at a secure computer.
-If not supplied, Keytool prompts you to enter the password. In this 
-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 
--alias alias_name -keyalg RSA -validity 9500</pre>
-
-<p>Running the example command above, Keytool prompts you to provide
-passwords for the keystore and key, and to provide the Distinguished
-Name fields for your key. It then generates the keystore as a file called
-<code>my-release-key.keystore</code>. The keystore and key are 
-protected by the passwords you entered. The keystore contains 
-a single key, valid for 9500 days. The alias is a name that you &mdash;
-will use later, to refer to this keystore when signing your application. </p>
-
-<p>For more information about Keytool, see the documentation at
-<a
-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>Signing Your Application</h3>
-
-<p>When you are ready to actually sign your .apk for release, you can do so
-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>
-
-<p>To sign your application, you run Jarsigner, referencing both the
-application's .apk and the keystore containing the private key with which to
-sign the .apk. The table below shows the options you could use. <p>
-
-<table>
-<tr>
-<th>Jarsigner Option</th>
-<th>Description</th>
-</tr>
-<tr>
-<td><code>-keystore&nbsp;&lt;keystore-name&gt;.keystore</code></td><td>The name of
-the keystore containing your private key.</td>
-</tr>
-<tr>
-<td><code>-verbose</code></td><td>Enable verbose output.</td>
-</tr>
-<tr>
-<td><code>-storepass &lt;password&gt;</code></td><td><p>The password for the
-keystore. </p><p>As a security precaution, do not include this option 
-in your command line unless you are working at a secure computer.
-If not supplied, Jarsigner prompts you to enter the password. In this 
-way, your password is not stored in your shell history.</p></td>
-</tr>
-<tr>
-<td><code>-keypass &lt;password&gt;</code></td><td><p>The password for the private
-key. </p><p>As a security precaution, do not include this option 
-in your command line unless you are working at a secure computer.
-If not supplied, Jarsigner prompts you to enter the password. In this 
-way, your password is not stored in your shell history.</p></td>
-</tr>
-</table>
-
-<p>Here's how you would use Jarsigner to sign an application package called
-<code>my_application.apk</code>, using the example keystore created above. 
-</p>
-
-<pre>$ jarsigner -verbose -keystore my-release-key.keystore 
-my_application.apk alias_name</pre>
-
-<p>Running the example command above, Jarsigner prompts you to provide
-passwords for the keystore and key. It then modifies the APK 
-in-place, meaning the .apk is now signed. Note that you can sign an 
-APK multiple times with different keys.</p>
-
-<p>To verify that your .apk is signed, you can use a command like this:</p>
-
-<pre>$ jarsigner -verify my_signed.apk</pre>
-
-<p>If the .apk is signed properly, Jarsigner prints "jar verified". 
-If you want more details, you can try one of these commands:</p>
-
-<pre>$ jarsigner -verify -verbose my_application.apk</pre>
-
-<p>or</p>
-
-<pre>$ jarsigner -verify -verbose -certs my_application.apk</pre>
-
-<p>The command above, with the <code>-certs</code> option added, will show you the 
-"CN=" line that describes who created the key.</p>
-
-<p class="note">Note: if you see "CN=Android Debug", this means the .apk was
-signed with the debug key generated by the Android SDK. If you intend to release
-your application, you must sign it with your private key instead of the debug
-key.</p>
-
-<p>For more information about Jarsigner, see the documentation at
-<a 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="secure-key">Securing Your Private Key</h3>
-
-<p>Maintaining the security of your private key is of critical importance, both
-to you and to the user. If you allow someone to use your key, or if you leave
-your keystore and passwords in an unsecured location such that a third-party
-could find and use them, your authoring identity and the trust of the user
-are compromised. </p>
-
-<p>If a third party should manage to take your key without your knowledge or 
-permission, that person could sign and distribute applications that maliciously
-replace your authentic applications or corrupt them. Such a person could also
-sign and distribute applications under your identity that attack other 
-applications or the system itself, or corrupt or steal user data. </p>
-
-<p>Your reputation as a developer entity depends on your securing your private
-key properly, at all times, until the key is expired. Here are some tips for
-keeping your key secure: </p>
-
-<ul>
-<li>Select strong passwords for the keystore and key.</li>
-<li>When you generate your key with Keytool, <em>do not</em> supply the 
-<code>-storepass</code> and <code>-keypass</code> options at the command line. 
-If you do so, your passwords will be available in your shell history, 
-which any user on your computer could access.</li>
-<li>Similarly, when signing your applications with Jarsigner, 
-<em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code> 
-options at the command line. </li>
-<li>Do not give or lend anyone your private key, and do not let unauthorized
-persons know your keystore and key passwords.</li>
-</ul>
-
-<p>In general, if you follow common-sense precautions when generating, using,
-and storing your key, it will remain secure. </p>
-
-<h2>Expiry of the Debug Certificate</h2>
-
-<p>The self-signed certificate used to sign your application in debug mode (the default on 
-Eclipse/ADT and Ant builds) will have an expiration date of 365 days from its creation date.</p>
-
-<p>When the certificate expires, you will get a build error. On Ant builds, the error 
-looks like this:</p>
-
-<pre>debug:
-[echo] Packaging bin/samples-debug.apk, and signing it with a debug key...
-[exec] Debug Certificate expired on 8/4/08 3:43 PM</pre>
-
-<p>In Eclipse/ADT, you will see a similar error in the Android console.</p>
-
-<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, 
-the file is stored in <code>~/.android</code>. OOn Windows XP, the file is stored in <code>
-C:\Documents and Settings\&lt;user&gt;\Local Settings\Application Data\Android</code>. 
-On Windows Vista, the file is stored in <code>
-C:\Users\&lt;user&gt;\AppData\Local\Android</code>.</p>
-
-<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p>
-
-<p>Note that, if your development machine is using a non-Gregorian locale, the build 
-tools may erroneously generate an already-expired debug certificate, so that you get an 
-error when trying to compile your application. For workaround information, see the 
-troubleshooting topic <a href="{@docRoot}kb/troubleshooting.html#signingcalendar">
-I&nbsp;can't&nbsp;compile my app because the build tools generated an expired debug 
-certificate</a>. </p>
\ No newline at end of file
diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd
index 7ba7968..1e13ace 100644
--- a/docs/html/guide/developing/tools/avd.jd
+++ b/docs/html/guide/developing/tools/avd.jd
@@ -21,13 +21,12 @@ page.title=Android Virtual Devices
         <li><a href="#createavd">Creating the AVD</a></li>
         <li><a href="#hardwareopts">Setting hardware emulation options</a></li>
         <li><a href="#location">Default location of the AVD files</a></li>
-        <li><a href="#createavdopts">Command-line options, create avd</a></li>
       </ol>
     </li>
     <li><a href="#managing">Managing AVDs</a>
       <ol>
         <li><a href="#moving">Moving an AVD</a></li>
-        <li><a href="#updating">Deleting an AVD</a></li>
+        <li><a href="#updating">Updating an AVD</a></li>
         <li><a href="#deleting">Deleting an AVD</a></li>
       </ol>
     </li>
@@ -35,7 +34,8 @@ page.title=Android Virtual Devices
   </ol>
   <h2>See Also</h2>
   <ol>
-    <li>Android <a href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a></li>
+    <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android 
+        Emulator</a></li>
   </ol>
 </div>
 </div>
@@ -366,6 +366,10 @@ the <code>-p</code> option to place the AVD directory in another location.
 The  AVD's .ini file remains in the .android directory on the network
 drive, regardless of the location of the AVD directory. </p>
 
+<h2 id="managing">Managing AVDs</h2>
+
+<p>The sections below provide more information about how to manage AVDs once you've created them. </p>
+
 <h3 id="moving">Moving an AVD</h3>
 
 <p>If you want to move or rename an AVD, you can do so using this command:</p>
@@ -455,7 +459,7 @@ files.</td>
 </tr>
 <tr>
   <td><code>-s &lt;name&gt;</code> or <br>
-      <code>-s &lt;dimensions&gt;</code> </td>
+      <code>-s &lt;width&gt;-&lt;height&gt;</code> </td>
   <td>The skin to use for this AVD, identified by name or dimensions.</td>
   <td>The android tool scans for a matching skin by name or dimension in the
 <code>skins/</code> directory of the target referenced in the <code>-t