Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Robert Ly
2010-12-29 14:59:35 -08:00
committed by Android (Google) Code Review
parent 31de0f0be0 70628c7aaf
commit 91f901d906
5 changed files with 549 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

306
docs/html/guide/developing/building/building-cmdline.jd Normal file
View File

@@ -0,0 +1,306 @@
page.title=Building and Running Applications in Other IDEs
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#DebugMode">Building in debug mode</a></li>
<li><a href="#ReleaseMode">Building in release mode</a></li>
<li><a href="#RunningOnEmulator">Running on an emulator</a></li>
<li><a href="#RunningOnDevice">Running on a device</a></li>
</ol>
</div>
</div>
<p>There are two ways to build your application using the Ant build script: one for
testing/debugging your application &mdash; <em>debug mode</em> &mdash; and one for building your
final package for release &mdash; <em>release mode</em>. Regardless of which way you build your application,
it must be signed before it can install on an emulator or device&mdash;with a debug key when building
in debug mode and with your own private key when building in release mode.</p>
<p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile
and build your project. This will create the .apk file that you can install on an emulator or device.
When you build in debug mode, the .apk file is automatically signed by the SDK tools with
a debug key, so it's instantly ready for installation onto an emulator or attached
development device. You cannot distribute an application that is signed with a debug key.
When you build in release mode, the .apk file is <em>unsigned</em>, so you
must manually sign it with your own private key, using Keytool and Jarsigner.</p>
<p>It's important that you read and understand <a href=
"{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>, particularly once
you're ready to release your application and share it with end-users. That document describes the
procedure for generating a private key and then using it to sign your .apk file. If you're just
getting started, however, you can quickly run your applications on an emulator or your own
development device by building in debug mode.</p>
<p>If you don't have Ant, you can obtain it from the <a href="http://ant.apache.org/">Apache Ant
home page</a>. Install it and make sure it is in your executable PATH. Before calling Ant, you
need to declare the JAVA_HOME environment variable to specify the path to where the JDK is
installed.</p>
<p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install
in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of
the space. To fix the problem, you can specify the JAVA_HOME variable like this:
<pre>set JAVA_HOME=c:\Progra~1\Java\&lt;jdkdir&gt;
</pre>
The easiest solution, however, is to install JDK in a non-space directory, for example:
<pre>c:\java\jdk1.6.0_02</pre>
<h2 id="DebugMode">Building in debug mode</h2>
<p>For immediate application testing and debugging, you can build your application in debug mode
and immediately install it on an emulator. In debug mode, the build tools automatically sign your
application with a debug key and optimize the package with {@code zipalign}.</p>
<p>To build in debug mode:</p>
<ol>
<li>Open a command-line and navigate to the root of your project directory.</li>
<li>Use Ant to compile your project in debug mode:
<pre>
ant debug
</pre>
<p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named
<code>&lt;your_project_name&gt;-debug.apk</code>. The file is already signed with
the debug key and has been aligned with
<a href="{@docRoot}/guide/developing/tools/zipalign.html"><code>zipalign</code></a>.
</p>
</li>
</ol>
<p>Each time you change a source file or resource, you must run Ant again in order to package up
the latest version of the application.</p>
<p>To install and run your application on an emulator, see the following section about <a href=
"#RunningOnEmulator">Running on the Emulator</a>.</p>
<h2 id="ReleaseMode">Building in release mode</h2>
<p>When you're ready to release and distribute your application to end-users, you must build your
application in release mode. Once you have built in release mode, it's a good idea to perform
additional testing and debugging with the final .apk.</p>
<p>Before you start building your application in release mode, be aware that you must sign the
resulting application package with your private key, and should then align it using the {@code
zipalign} tool. There are two approaches to building in release mode: build an unsigned package
in release mode and then manually sign and align the package, or allow the build script to sign
and align the package for you.</p>
<h3 id="ManualReleaseMode">Build unsigned</h3>
<p>If you build your application <em>unsigned</em>, then you will need to manually sign and align
the package.</p>
<p>To build an <em>unsigned</em> .apk in release mode:</p>
<ol>
<li>Open a command-line and navigate to the root of your project directory.</li>
<li>Use Ant to compile your project in release mode:
<pre>
ant release
</pre>
</li>
</ol>
<p>This creates your Android application .apk file inside the project <code>bin/</code>
directory, named <code><em>&lt;your_project_name&gt;</em>-unsigned.apk</code>.</p>
<p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't
be installed until signed with your private key.</p>
<p>Once you have created the unsigned .apk, your next step is to sign the .apk with your private
key and then align it with {@code zipalign}. To complete this procedure, read <a href=
"{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users.
You should test the final build on different devices or AVDs to ensure that it
runs properly on different platforms.</p>
<h3 id="AutoReleaseMode">Build signed and aligned</h3>
<p>If you would like, you can configure the Android build script to automatically sign and align
your application package. To do so, you must provide the path to your keystore and the name of
your key alias in your project's {@code build.properties} file. With this information provided,
the build script will prompt you for your keystore and alias password when you build in release
mode and produce your final application package, which will be ready for distribution.</p>
<p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that
you enter during the build process <strong>will be visible</strong>. If you are concerned about
your keystore and alias password being visible on screen, then you may prefer to perform the
application signing manually, via Jarsigner (or a similar tool). To instead perform the signing
procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with
<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>To specify your keystore and alias, open the project {@code build.properties} file (found in
the root of the project directory) and add entries for {@code key.store} and {@code key.alias}.
For example:</p>
<pre>
key.store=path/to/my.keystore
key.alias=mykeystore
</pre>
<p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p>
<ol>
<li>Open a command-line and navigate to the root of your project directory.</li>
<li>Use Ant to compile your project in release mode:
<pre>
ant release
</pre>
</li>
<li>When prompted, enter you keystore and alias passwords.
<p class="caution"><strong>Caution:</strong> As described above, your password will be
visible on the screen.</p>
</li>
</ol>
<p>This creates your Android application .apk file inside the project <code>bin/</code>
directory, named <code><em>&lt;your_project_name&gt;</em>-release.apk</code>. This .apk file has
been signed with the private key specified in {@code build.properties} and aligned with {@code
zipalign}. It's ready for installation and distribution.</p>
<h3>Once built and signed in release mode</h3>
<p>Once you have signed your application with a private key, you can install and run it on an
<a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. You can
also try installing it onto a device from a web server. Simply upload the signed .apk to a web
site, then load the .apk URL in your Android web browser to download the application and begin
installation. (On your device, be sure you have enabled
<em>Settings &gt; Applications &gt; Unknown sources</em>.)</p>
<h2 id="RunningOnEmulator">Running on the emulator</h2>
<p>Before you can run your application on the Android Emulator, you must <a href=
"{@docRoot}guide/developing/devices/managing-avds.html">create an AVD</a>.</p>
<p>To run your application:</p>
<ol>
<li>
<strong>Open the SDK and AVD Manager and launch a virtual device</strong>
<p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool with no
arguments:</p>
<pre>
android
</pre>
<p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p>
</li>
<li>
<strong>Install your application</strong>
<p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the
emulator:</p>
<pre>
adb install <em>&lt;path_to_your_bin&gt;</em>.apk
</pre>
<p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/}
directory after you build your application.</p>
<p>If there is more than one emulator running, you must specify the emulator upon which to
install the application, by its serial number, with the <code>-s</code> option. For
example:</p>
<pre>
adb -s emulator-5554 install <em>path/to/your/app</em>.apk
</pre>
<p>To see a list of available device serial numbers, execute {@code adb devices}.</p>
</li>
</ol>
<p>If you don't see your application on the emulator, try closing the emulator and launching the
virtual device again from the SDK and AVD Manager. Sometimes when you install an application for the
first time, it won't show up in the application launcher or be accessible by other applications.
This is because the package manager usually examines manifests completely only on emulator
startup.</p>
<p>Be certain to create multiple AVDs upon which to test your application. You should have one
AVD for each platform and screen type with which your application is compatible. For instance, if
your application compiles against the Android 1.5 (API Level 3) platform, you should create an
AVD for each platform equal to and greater than 1.5 and an AVD for each <a href=
"{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your
application on each one.</p>
<p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, you can
build your application and install it on the emulator in one simple step. Navigate to the root of
your project directory and use Ant to compile the project with <em>install mode</em>: <code>ant
install</code>. This will build your application, sign it with the debug key, and install it on
the currently running emulator.</p>
<h2 id="RunningOnDevice">Running on a device</h2>
<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>
<ul>
<li>Ensure that your application is debuggable by setting the
<code>android:debuggable</code> attribute of the <code>&lt;application&gt;</code>
element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>
<li>Enable USB Debugging on your device. You can find the setting on most Android devices by
going to <strong>Settings > Applications > Development > USB debugging</strong>.</li>
<li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for
Development</a> for more information.</p>
<p>Once your device is set up and connected via USB, navigate to your SDK's <code>platform-tools/</code>
directory and install the <code>.apk</code> on the device:</p>
<pre>
adb -d install <em>path/to/your/app</em>.apk
</pre>
<p>The {@code -d} flag specifies that you want to use the attached device (in case you also have
an emulator running).</p>
<p>For more information on the tools used above, please see the following documents:</p>
<ul>
<li><a href="{@docRoot}guide/developing/tools/android.html">android Tool</a></li>
<li><a href="{@docRoot}guide/developing/devices/emulator.html">Android Emulator</a></li>
<li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li>
</ul>
<h2 id="Signing">Application Signing</h2>
<p>As you begin developing Android applications, understand that all Android applications must be
digitally signed before the system will install them on an emulator or device. There are two ways
to do this: with a <em>debug key</em> (for immediate testing on an emulator or development
device) or with a <em>private key</em> (for application distribution).</p>
<p>The Android build tools help you get started by automatically signing your .apk files with a
debug key at build time. This means that you can compile your application and install it on the
emulator without having to generate your own private key. However, please note that if you intend
to publish your application, you <strong>must</strong> sign the application with your own private
key, rather than the debug key generated by the SDK tools.</p>
<p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key,
prior to installing them on an emulator or development device. This means that you can quickly
run your application from Eclipse without having to generate your own private key. No specific
action on your part is needed, provided ADT has access to Keytool.However, please note that if
you intend to publish your application, you <strong>must</strong> sign the application with your
own private key, rather than the debug key generated by the SDK tools.</p>
<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your
Applications</a>, which provides a thorough guide to application signing on Android and what it
means to you as an Android application developer. The document also includes a guide to exporting
and signing your application with the ADT's Export Wizard.</p>

163
docs/html/guide/developing/building/building-eclipse.jd Normal file
View File

@@ -0,0 +1,163 @@
page.title=Building and Running Applications in Eclipse
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#RunningOnEmulatorEclipse">Running on an Emulator</a></li>
<li><a href="#RunningOnDeviceEclipse">Running on a Device</a></li>
<li><a href="#RunConfig">Creating a Run Configuration</a></li>
</ol>
</div>
</div>
<p>Eclipse and ADT provide an environment where most of the details of the build process are
hidden from you. By default, the build process constantly runs in the background as you make
changes to your project.</p>
<p>When Eclipse automatically builds your application, it enables debugging and signs the
<code>.apk</code> with a debug key, by default. When you run the application,
Eclipse invokes ADB and installs your application to a device or emulator, so you do not have to
manually perform these tasks. Since most of the build process is taken care of by Eclipse, the
following topics show you how to run an application, which will automatically build your
application as well.</p>
<p>To distribute your application, however, you must build your application in release mode and sign the
<code>.apk</code> file with your own private key.</p>
<p>This document shows you how to run your application on an emulator or a real device
from Eclipse&mdash;all of which is done using the debug version of your application.
For more information about how to sign your application with a private key for release, see <a href=
"{@docRoot}guide/publishing/app-signing.html#ExportWizard">Signing Your Applications</a></p>
<h2 id="RunningOnEmulatorEclipse">Running on the emulator</h2>
<p>Before you can run your application on the Android Emulator, you must <a href=
"{@docRoot}guide/developing/devices/managing-avds.html">create an AVD</a>.</p>
<p>To run (or debug) your application, select <strong>Run</strong> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin will
automatically create a default run configuration for the project. Eclipse will then perform the
following:</p>
<ol>
<li>Compile the project (if there have been changes since the last build).</li>
<li>Create a default run configuration (if one does not already exist for the project).</li>
<li>Install and start the application on an emulator (or device), based on the Deployment
Target defined by the run configuration.
<p>By default, Android run configurations use an "automatic target" mode for selecting a
device target. For information on how automatic target mode selects a deployment target, see
<a href="#AutoAndManualTargetModes">Automatic and manual target modes</a> below.</p>
</li>
</ol>
<p>If you run the application with the Debug option, the application will start in the "Waiting For Debugger" mode. Once the debugger
is attached, Eclipse opens the Debug perspective and starts the application's main activity. Otherwise, if you run the
application with the normal Run option, Eclipse installs the application on the device and launches the main activity.</p>
<p>To set or change the run configuration used for your project, use the run configuration
manager. See the section below about <a href="#RunConfig">Creating a Run Configuration</a> for more information.</p>
<p>Be certain to create multiple AVDs upon which to test your application. You should have one
AVD for each platform and screen type with which your application is compatible. For instance, if
your application compiles against the Android 1.5 (API Level 3) platform, you should create an
AVD for each platform equal to and greater than 1.5 and an AVD for each <a href=
"{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your
application on each one.</p>
<h2 id="RunningOnDeviceEclipse">Running on a device</h2>
<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>
<ul>
<li>Ensure that your application is debuggable by setting the
<code>android:debuggable</code> attribute of the <code>&lt;application&gt;</code>
element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>
<li>Enable USB Debugging on your device. You can find the setting on most Android devices by
going to <strong>Settings > Applications > Development > USB debugging</strong>.</li>
<li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}guide/developing/device.html">Connecting Hardware Devices</a>
for more information.</p>
<p>Once set up and your device is connected via USB, install your application on the device by
selecting <strong>Run</strong> &gt; <strong>Run</strong> (or <strong>Run</strong> &gt;
<strong>Debug</strong>) from the Eclipse menu bar.</p>
<h2 id="RunConfig">Creating a Run Configuration</h2>
<p>The run configuration specifies the project to run, the Activity to start, the emulator or
connected device to use, and so on. When you first run a project as an <em>Android
Application</em>, ADT will automatically create a run configuration. The default run
configuration will launch the default project Activity and use automatic target mode for device
selection (with no preferred AVD). If the default settings don't suit your project, you can
customize the run configuration or even create a new one.</p>
<p>To create or modify a run configuration, refer to the Eclipse documentation on how to create Run configurations.
The following steps highlight the important things you need to do for an Android project:</p>
<ol>
<li>Open the run configuration manager from the Run Menu.</li>
<li>Expand the <strong>Android Application</strong> item and create a new configuration or open
an existing one.
</li>
<li>With the Run Configuration selected, adjust your desired run configuration settings:
<ul>
<li>In the Android tab, specify the Project and Activity to launch.
</li>
<li><p>In the Target tab, consider whether you'd like to use Manual or Automatic mode when
selecting an AVD to run your application. See the following section on <a href=
"#AutoAndManualTargetModes">Automatic and manual target modes</a>).</p>
<p>You can specify any emulator options to the Additional Emulator Command Line Options
field. For example, you could add <code>-scale 96dpi</code> to scale the AVD's screen to an
accurate size, based on the dpi of your computer monitor. For a full list of emulator
options, see the <a href="{@docRoot}guide/developing/tools/emulator.html">Android
Emulator</a> document.</p>
</li>
</ul>
</li>
</ol>
<h4 id="AutoAndManualTargetModes">Automatic and manual target modes</h4>
<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to
select an AVD. In this mode, ADT will select an AVD for the application in the following
manner:</p>
<ol>
<li>If there's a device or emulator already running and its AVD configuration meets the
requirements of the application's build target, the application is installed and run upon
it.</li>
<li>If there's more than one device or emulator running, each of which meets the requirements
of the build target, a "device chooser" is shown to let you select which device to use.</li>
<li>If there are no devices or emulators running that meet the requirements of the build
target, ADT looks at the available AVDs. If there is an AVD that matches the build target of the project,
ADT chooses that AVD. If the AVD versions are newer than the build target of the project, ADT chooses
the oldest possible version of an AVD that meets the project's build target requirement.</li>
<li>If there are no suitable AVDs, the application is not installed a console error warning tells
you that there is no existing AVD that meets the build target requirements.</li>
</ol>
<p>However, if a "preferred AVD" is selected in the run configuration, then the application will
<em>always</em> be deployed to that AVD. If it's not already running, then a new emulator will be
launched.</p>
<p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" is
presented every time that your application is run, so that you can select which AVD to use.</p>

80
docs/html/guide/developing/building/index.jd Normal file
View File

@@ -0,0 +1,80 @@
page.title=Building and Running Applications
@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 Android
Market, 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}guide/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="/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>
<p><img src="/images/build.png" /></p>
<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>

BIN
docs/html/images/build-simplified.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/html/images/build.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 103 KiB