From 70628c7aaf6ada93ae1599deff63d0c13c644ed8 Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Wed, 22 Dec 2010 10:59:38 -0800 Subject: Doc change: restructuring changes for building and running section of dev guide Change-Id: I11072ab34f8cafcf9ab7bf1c9f6b5869d9e2ced2 --- .../guide/developing/building/building-cmdline.jd | 306 +++++++++++++++++++++ .../guide/developing/building/building-eclipse.jd | 163 +++++++++++ docs/html/guide/developing/building/index.jd | 80 ++++++ 3 files changed, 549 insertions(+) create mode 100644 docs/html/guide/developing/building/building-cmdline.jd create mode 100644 docs/html/guide/developing/building/building-eclipse.jd create mode 100644 docs/html/guide/developing/building/index.jd (limited to 'docs/html/guide') diff --git a/docs/html/guide/developing/building/building-cmdline.jd b/docs/html/guide/developing/building/building-cmdline.jd new file mode 100644 index 0000000..ff8e236 --- /dev/null +++ b/docs/html/guide/developing/building/building-cmdline.jd @@ -0,0 +1,306 @@ +page.title=Building and Running Applications in Other IDEs +@jd:body + +
+ +
+ +

There are two ways to build your application using the Ant build script: one for + testing/debugging your application — debug mode — and one for building your + final package for release — release mode. Regardless of which way you build your application, + it must be signed before it can install on an emulator or device—with a debug key when building + in debug mode and with your own private key when building in release mode.

+ +

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 unsigned, so you + must manually sign it with your own private key, using Keytool and Jarsigner.

+ +

It's important that you read and understand Signing Your Applications, 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.

+ +

If you don't have Ant, you can obtain it from the Apache Ant + home page. 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.

+ +

Note: When installing JDK on Windows, the default is to install + in the "Program Files" directory. This location will cause ant to fail, because of + the space. To fix the problem, you can specify the JAVA_HOME variable like this: + 

set JAVA_HOME=c:\Progra~1\Java\<jdkdir>
+
+ + The easiest solution, however, is to install JDK in a non-space directory, for example: + + 
c:\java\jdk1.6.0_02
+ +

Building 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 and optimize the package with {@code zipalign}.

+ +

To build in debug mode:

+ +
    +
  1. Open a command-line and navigate to the root of your project directory.
    2. +
  2. Use Ant to compile your project in debug mode: + 
    +ant debug
+
    + +

    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 + zipalign. +

    +
    3. +
+ +

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.

+ +

To install and run your application on an emulator, see the following section about Running on the Emulator.

+ +

Building in release mode

+ +

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.

+ +

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
+
    +
    3. +
+ +

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. + You should test the final build on different devices or AVDs to ensure that it + runs properly on different platforms.

+ +

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, build 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 and run it on an + emulator or device. 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 + Settings > Applications > Unknown sources.)

+ +

Running on the emulator

+ +

Before you can run your application on the Android Emulator, you must create an AVD.

+ +

To run your application:

+ +
    +
  1. + Open the SDK and AVD Manager and launch a virtual device + +

    From your SDK's platform-tools/ directory, execute the {@code android} tool with no + arguments:

    + 
    +android
+
    + +

    In the Virtual Devices view, select an AVD and click Start.

    +
    2. + +
  2. + Install your application + +

    From your SDK's tools/ directory, install the {@code .apk} on the + emulator:

    + 
    +adb install <path_to_your_bin>.apk
+
    + +

    Your .apk file (signed with either a release or debug key) is in your project {@code bin/} + directory after you build your application.

    + +

    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 -s option. For + example:

    + 
    +adb -s emulator-5554 install path/to/your/app.apk
+
    + +

    To see a list of available device serial numbers, execute {@code adb devices}.

    +
    3. +
+ +

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.

+ +

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 screen type you support, then test your + application on each one.

+ +

Tip: If you have only one 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 install mode: ant + install. This will build your application, sign it with the debug key, and install it on + the currently running emulator.

+ +

Running on a device

+ +

Before you can run your application on a device, you must perform some basic setup for your + device:

+ + + +

Read Setting up a Device for + Development for more information.

+ +

Once your device is set up and connected via USB, navigate to your SDK's platform-tools/ + directory and install the .apk on the device:

+ 
+adb -d install path/to/your/app.apk 
+
+ +

The {@code -d} flag specifies that you want to use the attached device (in case you also have + an emulator running).

+ +

For more information on the tools used above, please see the following documents:

+ + + +

Application Signing

+ +

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 debug key (for immediate testing on an emulator or development + device) or with a private key (for application distribution).

+ +

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 must sign the application with your own private + key, rather than the debug key generated by the SDK tools.

+ +

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 must sign the application with your + own private key, rather than the debug key generated by the SDK tools.

+ +

Please read Signing Your + Applications, 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.

\ No newline at end of file diff --git a/docs/html/guide/developing/building/building-eclipse.jd b/docs/html/guide/developing/building/building-eclipse.jd new file mode 100644 index 0000000..4de4f31 --- /dev/null +++ b/docs/html/guide/developing/building/building-eclipse.jd @@ -0,0 +1,163 @@ +page.title=Building and Running Applications in Eclipse +@jd:body + +
+ +
+ +

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.

+ +

When Eclipse automatically builds your application, it enables debugging and signs the + .apk 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.

+ +

To distribute your application, however, you must build your application in release mode and sign the + .apk file with your own private key.

+ +

This document shows you how to run your application on an emulator or a real device + from Eclipse—all of which is done using the debug version of your application. + For more information about how to sign your application with a private key for release, see Signing Your Applications

+ +

Running on the emulator

+ +

Before you can run your application on the Android Emulator, you must create an AVD.

+ +

To run (or debug) your application, select Run > Run (or + Run > Debug) from the Eclipse menu bar. The ADT plugin will + automatically create a default run configuration for the project. Eclipse will then perform the + following:

+ +
    +
  1. Compile the project (if there have been changes since the last build).
    2. + +
  2. Create a default run configuration (if one does not already exist for the project).
    3. + +
  3. Install and start the application on an emulator (or device), based on the Deployment + Target defined by the run configuration. + +

    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 + Automatic and manual target modes below.

    +
    4. +
+ +

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.

+ +

To set or change the run configuration used for your project, use the run configuration + manager. See the section below about Creating a Run Configuration for more information.

+ +

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 screen type you support, then test your + application on each one.

+ +

Running on a device

+ +

Before you can run your application on a device, you must perform some basic setup for your + device:

+ + + +

Read Connecting Hardware Devices + for more information.

+ +

Once set up and your device is connected via USB, install your application on the device by + selecting Run > Run (or Run > + Debug) from the Eclipse menu bar.

+ +

Creating a Run Configuration

+ +

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 Android + Application, 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.

+ +

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:

+ +
    +
  1. Open the run configuration manager from the Run Menu.
    2. + +
  2. Expand the Android Application item and create a new configuration or open + an existing one. +
    3. + +
  3. With the Run Configuration selected, adjust your desired run configuration settings: +
      +
    • In the Android tab, specify the Project and Activity to launch. +
      • +

    • 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 Automatic and manual target modes).

      + +

      You can specify any emulator options to the Additional Emulator Command Line Options + field. For example, you could add -scale 96dpi 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 Android + Emulator document.

      +
      • +
    +
    4. +
+ +

Automatic and manual target modes

+ +

By default, a run configuration uses the automatic target mode in order to + select an AVD. In this mode, ADT will select an AVD for the application in the following + manner:

+ +
    +
  1. 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.
    2. + +
  2. 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.
    3. + +
  3. 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.
    4. + +
  4. 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.
    5. +
+ +

However, if a "preferred AVD" is selected in the run configuration, then the application will + always be deployed to that AVD. If it's not already running, then a new emulator will be + launched.

+ +

If your run configuration uses manual mode, then the "device chooser" is + presented every time that your application is run, so that you can select which AVD to use.

\ No newline at end of file diff --git a/docs/html/guide/developing/building/index.jd b/docs/html/guide/developing/building/index.jd new file mode 100644 index 0000000..83a7bb3 --- /dev/null +++ b/docs/html/guide/developing/building/index.jd @@ -0,0 +1,80 @@ +page.title=Building and Running Applications +@jd:body + +
+
+

In this document

+
    +
  1. A Detailed Look at the Build Process
    2. +
+
+
+ +

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 .dex files (.class files + converted to Dalvik byte code), a binary version of the AndroidManifest.xml file, compiled + resources (resources.arsc) and uncompiled resource files for your application.

+ +

If you are developing in Eclipse, the ADT plugin incrementally builds your project as you + make changes to the source code. Eclipse outputs an .apk file automatically to the bin folder of + the project, so you do not have to do anything extra to generate the .apk.

+ +

If you are developing in a non-Eclipse environment, you can build your project with the + generated build.xml Ant file that is in the project directory. The Ant file calls targets that + automatically call the build tools for you.

+ +

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.

+ +

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 Signing Your Applications.

+ +

The following diagram depicts the components involved in building and running an application:

+ + + +

A Detailed Look at the Build Process

+ +

The build process involves many tools and processes that generate intermediate files on the + way to producing an .apk. 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:

+ +

+ +

The general process for a typical build is outlined below:

+ + + -- cgit v1.1