| page.title=Developing In Other IDEs |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#CreatingAProject">Creating an Android Project</a></li> |
| <li><a href="#Signing">Preparing to Sign Your Application</a></li> |
| <li><a href="#Building">Building Your Application</a> |
| <ol> |
| <li><a href="#DebugMode">Building in debug mode</a></li> |
| <li><a href="#ReleaseMode">Building in release mode</a></li> |
| </ol> |
| </li> |
| <li><a href="#Running">Running Your Application</a></li> |
| <li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li> |
| </ol> |
| |
| <h2>See also</h2> |
| <ol> |
| <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> |
| <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> |
| <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>The recommended way to develop an Android application is to use |
| <a href="{@docRoot}guide/developing/eclipse-adt.html">Eclipse with the ADT plugin</a>. |
| The ADT plugin provides editing, building, debugging, and .apk packaging and signing functionality |
| integrated right into the IDE.</p> |
| |
| <p>However, if you'd rather develop your application in another IDE, such as IntelliJ, |
| or in a basic editor, such as Emacs, you can do that instead. The SDK |
| includes all the tools you need to set up an Android project, build it, debug it and then |
| package it for distribution. This document is your guide to using these tools.</p> |
| |
| |
| <h2 id="EssentialTools">Essential Tools</h2> |
| |
| <p>When developing in IDEs or editors other than Eclipse, you'll require |
| familiarity with the following Android SDK tools:</p> |
| |
| <dl> |
| <dt><a href="{@docRoot}guide/developing/tools/othertools.html#android">android</a></dt> |
| <dd>To create/update Android projects and to create/move/delete AVDs.</dd> |
| <dt><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></dt> |
| <dd>To run your Android applications on an emulated Android platform.</dd> |
| <dt><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></dt> |
| <dd>To interface with your emulator or connected device (install apps, |
| shell the device, issue commands, etc.). |
| </dd> |
| </dl> |
| |
| <p>In addition to the above tools, included with the SDK, you'll use the following |
| open source and third-party tools:</p> |
| |
| <dl> |
| <dt>Ant</dt> |
| <dd>To compile and build your Android project into an installable .apk file.</dd> |
| <dt>Keytool</dt> |
| <dd>To generate a keystore and private key, used to sign your .apk file.</dd> |
| <dt>Jarsigner (or similar signing tool)</dt> |
| <dd>To sign your .apk file with a private key generated by keytool.</dd> |
| </dl> |
| |
| <p>In the topics that follow, you'll be introduced to each of these tools as necessary. |
| For more advanced operations, please read the respective documentation for each tool.</p> |
| |
| |
| <h2 id="CreatingAProject">Creating an Android Project</h2> |
| |
| <p>To create an Android project, you must use the <code>android</code> tool. When you create |
| a new project with <code>android</code>, it will generate a project directory |
| with some default application files, stub files, configuration files and a build file.</p> |
| |
| |
| <h3 id="CreatingANewProject">Creating a new Project</h3> |
| |
| <p>If you're starting a new project, use the <code>android create project</code> |
| command to generate all the necessary files and folders.</p> |
| |
| <p>To create a new Android project, open a command-line, |
| navigate to the <code>tools/</code> directory of your SDK and run:</p> |
| <pre> |
| android create project \ |
| --target <em><target_ID></em> \ |
| --name <em><your_project_name></em> \ |
| --path <em>/path/to/your/project</em> \ |
| --activity <em><your_activity_name></em> \ |
| --package <em><your_package_namespace></em> |
| </pre> |
| |
| <ul> |
| <li><code>target</code> is the "build target" for your application. It corresponds |
| 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 default {@link android.app.Activity} class. This class file |
| will be created for you inside |
| <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></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> |
| |
| <p>Here's an example:</p> |
| <pre> |
| android create project \ |
| --target 1 \ |
| --name MyAndroidApp \ |
| --path ./MyAndroidAppProject \ |
| --activity MyAndroidAppActivity \ |
| --package com.example.myandroid |
| </pre> |
| |
| <p>The tool generates the following files and directories:</p> |
| |
| <ul> |
| <li><code>AndroidManifest.xml</code> - The application manifest file, |
| synced to the specified Activity class for the project.</li> |
| <li><code>build.xml</code> - Build file for Ant.</li> |
| <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 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> |
| <li><code>gen/</code> - Holds <code>Ant</code>-generated files, such as <code>R.java</code>. </li> |
| <li><code>libs/</code> - Holds private libraries.</li> |
| <li><code>res/</code> - Holds project resources.</li> |
| <li><code>src/</code> - Holds source code.</li> |
| <li><code>tests/</code> - Holds a duplicate of all-of-the-above, for testing purposes.</li> |
| </ul> |
| |
| <p>Once you've created your project, you're ready to begin development. |
| You can move your project folder wherever you want for development, but keep in mind |
| that you must use the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> |
| (adb) — located in the SDK <code>tools/</code> directory — to send your application |
| to the emulator (discussed later). So you need access between your project solution and |
| the <code>tools/</code> folder.</p> |
| |
| <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> |
| |
| |
| <h3 id="UpdatingAProject">Updating a project</h3> |
| |
| <p>If you're upgrading a project from an older version of the Android SDK or want to create |
| 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) 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 --name <em><project_name></em> --target <em><target_ID></em> --path <em>path/to/your/project/</em> |
| </pre> |
| |
| <ul> |
| <li><code>target</code> is the "build target" for your application. It corresponds 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>path</code> is the location of your project directory.</li> |
| <li><code>name</code> is the name for the project. This is optional—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 --name MyApp --target 2 --path ./MyAppProject |
| </pre> |
| |
| |
| <h2 id="Signing">Preparing to Sign Your Application</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>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.</p> |
| |
| |
| |
| <h2 id="Building">Building Your Application</h2> |
| |
| <p>There are two ways to build your application: one for testing/debugging your application |
| — <em>debug mode</em> — and one for building your final package for release — |
| <em>release mode</em>. As described in the previous |
| section, your application must be signed before it can be installed on an emulator |
| or device.</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 is installed onto the 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 |
| (but only onto an emulator or attached development device). |
| 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: |
| <code>set JAVA_HOME=c:\Progra~1\Java\<jdkdir></code>. The easiest solution, however, is to |
| install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>.</p> |
| |
| |
| <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 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> |
| |
| <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 .apk file inside the project <code>bin/</code> |
| directory, named <code><em><your_project_name></em>-debug.apk</code>. The file |
| is already signed with the debug key and has been aligned with {@code zipalign}.</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="#Running">Running Your Application</a>.</p> |
| |
| |
| <h3 id="ReleaseMode">Building in release mode</h3> |
| |
| <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> |
| |
| <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> |
| </li> |
| </ol> |
| |
| <p>This creates your Android application .apk file inside the project <code>bin/</code> |
| directory, named <code><em><your_project_name></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><your_project_name></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>. |
| 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 > Applications > Unknown sources</em>.)</p> |
| |
| |
| <h2 id="Running">Running Your Application</h2> |
| |
| <p>Unless you'll be running your application on device hardware, |
| you need to launch an emulator upon which you will install your application. |
| An instance of the Android emulator runs a specific Android platform with specific device configuration |
| settings. The platform and configuration is defined with an Android Virtual Device (AVD). |
| So before you can launch your emulator, you must define an AVD.</p> |
| |
| <p>If you'll be running your application on device hardware, please read about |
| <a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> instead.</p> |
| |
| <ol> |
| <li><strong>Create an AVD</strong> |
| <ol> |
| <li>Open a command-line and navigate to your SDK package's |
| <code>tools/</code> directory.</li> |
| <li>First, you need to select a "deployment target." To view available targets, execute: |
| <pre>android list targets</pre> |
| <p>This will output a list of available Android targets, such as:</p> |
| <pre> |
| id:1 |
| Name: Android 1.1 |
| Type: platform |
| API level: 2 |
| Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P |
| id:2 |
| Name: Android 1.5 |
| Type: platform |
| API level: 3 |
| Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P |
| </pre> |
| <p>Find the target that matches the Android platform upon which you'd like |
| to run your application. Note the integer value of the <code>id</code> — |
| 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><your_avd_name></em> --target <em><target_ID></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, |
| press return to use all default values ("no" is the default).</li> |
| </li> |
| </ol> |
| </li> |
| |
| <li><strong>Launch an emulator</strong></li> |
| <p>From your SDK's <code>tools/</code> directory, launch an emulator |
| using an existing AVD (created above): |
| <pre>emulator -avd <em><your_avd_name></em></pre> |
| <p>An instance of the emulator will now launch, running the target and configuration |
| defined by your AVD.</p> |
| </li> |
| |
| <li><strong>Install your application</strong> |
| <p>From your SDK's <code>tools/</code> directory, install the .apk on the emulator: |
| <pre>adb install <em>/path/to/your/application</em>.apk</pre> |
| <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 /my/project/path/myapp.apk</pre> |
| </li> |
| <li><strong>Open your application</strong> |
| <p>In the emulator, open the list of available applications to find |
| and open your application.</p> |
| </li> |
| </ol> |
| |
| <p>If you don't see your application on the emulator. Try restarting the emulator |
| (with the same AVD). Sometimes when you install an Activity 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 class="note"><strong>Tip:</strong> 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 <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. |
| If there is more than one emulator currently running |
| when using the <code>install</code> command, it will fail — it can't select between the |
| multiple emulators.</p> |
| |
| <p>For more information on the tools used above, please see the following documents:</p> |
| <ul> |
| <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> |
| <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> |
| <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li> |
| </ul> |
| |
| |
| <h2 id="AttachingADebugger">Attaching a Debugger to Your Application</h2> |
| |
| <p>This section describes how to display debug information on the screen (such |
| as CPU usage), as well as how to hook up your IDE to debug running applications |
| on the emulator. </p> |
| |
| <p>Attaching a debugger is automated using the Eclipse plugin, |
| but you can configure other IDEs to listen on a debugging port to receive debugging |
| information:</p> |
| <ol> |
| <li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor |
| Server (DDMS)</a> tool, </strong> which |
| acts as a port forwarding service between your IDE and the emulator.</li> |
| <li><strong>Set |
| optional debugging configurations on |
| your emulator</strong>, such as blocking application startup for an Activity |
| until a debugger is attached. Note that many of these debugging options |
| can be used without DDMS, such as displaying CPU usage or screen refresh |
| rate on the emulator.</li> |
| <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> Read |
| about <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port"> |
| Configuring Your IDE to Attach to the Debugging Port</a>. </li> |
| </ol> |