From 47ef0c9954847c33335fd599e48334165e87f72d Mon Sep 17 00:00:00 2001 From: Xavier Ducrohet Date: Wed, 5 Oct 2011 12:12:46 -0700 Subject: [PATCH] Update dev guide for new build system and new lib system. Change-Id: I969e9659ca7f170c515caa1cddae39d91c2d8256 --- .../developing/building/building-cmdline.jd | 85 +++++++++--- docs/html/guide/developing/projects/index.jd | 122 +++++++++++------- .../developing/projects/projects-cmdline.jd | 21 +-- docs/html/guide/developing/tools/proguard.jd | 2 +- docs/html/guide/developing/tools/zipalign.jd | 2 +- docs/html/guide/publishing/app-signing.jd | 4 +- docs/html/guide/publishing/licensing.jd | 4 +- .../intl/ja/guide/developing/eclipse-adt.jd | 2 +- .../intl/ja/guide/developing/other-ide.jd | 4 +- docs/html/resources/articles/zipalign.jd | 2 +- 10 files changed, 162 insertions(+), 86 deletions(-) diff --git a/docs/html/guide/developing/building/building-cmdline.jd b/docs/html/guide/developing/building/building-cmdline.jd index ec918dc7beef2..d78a4f55c0690 100644 --- a/docs/html/guide/developing/building/building-cmdline.jd +++ b/docs/html/guide/developing/building/building-cmdline.jd @@ -18,6 +18,7 @@ parent.link=index.html
  • Running on the Emulator
  • Running on a Device
  • Application Signing
    • +
  • Ant Command Reference

    • See also

      @@ -58,11 +59,11 @@ Emulator

      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: + 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

      @@ -141,7 +142,7 @@ ant release

      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, + your key alias in your project's {@code ant.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.

      @@ -152,7 +153,7 @@ ant release 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 +

      To specify your keystore and alias, open the project {@code ant.properties} file (found in the root of the project directory) and add entries for {@code key.store} and {@code key.alias}. For example:

      @@ -180,16 +181,16 @@ ant release
 
   
      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
+  been signed with the private key specified in {@code ant.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 
+  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
      
@@ -260,10 +261,6 @@ adb -s emulator-5554 install path/to/your/app.apk
   device:
      
 
   
        
-    
      • Ensure that your application is debuggable by setting the
-    android:debuggable attribute of the <application>
-    element to true. As of ADT 8.0, this is done by default when you build in debug mode.
        • 
-
     
      • Enable USB Debugging on your device. You can find the setting on most Android devices by
     going to Settings > Applications > Development > USB debugging.
        • 
 
@@ -276,7 +273,7 @@ adb -s emulator-5554 install path/to/your/app.apk
   
        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 
+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
@@ -315,4 +312,60 @@ adb -d install path/to/your/app.apk
   
        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
+  and signing your application with the ADT's Export Wizard.
        
+
+  
        Ant Command Reference
        
+  
        ant clean
        
+  
        Cleans the project. If you include the all target before clean
+(ant all clean), other projects are also cleaned. For instance if you clean a
+test project, the tested project is also cleaned.
        
+
+  
        ant debug
        
+  
        Builds a debug package. Works on application, library, and test projects and compiles
+  dependencies as  needed.
        
+
+  
        ant emma debug
        
+  
        Builds a test project while building the tested project with instrumentation turned on.
+  This is used to run tests with code coverage enabled.
        
+
+  
        ant release
        
+  
        Builds a release package.
        
+
+  
        ant instrument
+  
        
+  
        Builds an instrumented debug package. This is generally called automatically when building a
+  test project with code coverage enabled (with the emma
+  target)
        
+
+  
        ant <build_target> install
        
+  
        Builds and installs a package. Using install by itself fails.
        
+
+  
        ant installd
        
+  
        Installs an already compiled debug package. This fails if the .apk is not
+  already built.
        
+
+  
        ant installr
        
+  
        Installs an already compiled release package. This fails if the .apk is not
+  already built.
        
+
+  
        ant installt
        
+  
        Installs an already compiled test package. Also installs the .apk of the
+  tested application. This fails if the .apk is not already built.
        
+
+  
        ant installi
        
+  
        Installs an already compiled instrumented package. This is generally not used manually as
+  it's called when installing a test package. This fails if the .apk is not already
+  built.
        
+
+   
        ant test
        
+   
        Runs the tests (for test projects). The tested and test .apk files must be
+   previously installed.
        
+
+  
        ant debug installt test
        
+  
        Builds a test project and the tested project, installs both .apk files, and
+  runs the tests.
        
+
+  
        ant emma debug installt test
        
+  
        Builds a test project and the tested project, installs both .apk files, and
+  runs the tests with code coverage enabled.
        
+
diff --git a/docs/html/guide/developing/projects/index.jd b/docs/html/guide/developing/projects/index.jd
index 273a405e2b5d4..ac8a1a59c948d 100644
--- a/docs/html/guide/developing/projects/index.jd
+++ b/docs/html/guide/developing/projects/index.jd
@@ -15,7 +15,7 @@ page.title=Managing Projects
         
 
         
      • Test Projects
        • 
-        
+
         
      • Testing a Library Project
        •
    @@ -43,7 +43,7 @@ page.title=Managing Projects
    Library Projects
    These projects contain shareable Android source code and resources that you can reference - in Android projects. This is useful when you have common code that you want to reuse. + in Android projects. This is useful when you have common code that you want to reuse. Library projects cannot be installed onto a device, however, they are pulled into the .apk file at build time.
    @@ -125,7 +125,7 @@ page.title=Managing Projects
    menu/
    -
    For XML files that define application menus. +
    For XML files that define application menus. See the Menus resource type.
    @@ -168,23 +168,33 @@ page.title=Managing Projects AndroidManifest.xml documentation for more information -
    build.properties
    +
    project.properties
    + +
    This file contains project settings, such as the build target. This file is integral to + the project, so maintain it in a source revision control system. To edit project + properties in Eclipse, right-click the project folder and select + Properties.
    + +
    local.properties
    + +
    Customizable computer-specific properties for the build system. If you use Ant to build + the project, this contains the path to the SDK installation. Because the content of the file + is specific to the local installation of the SDK, maintained it in a source + revision control system. If you use Eclipse, this file is not used.
    + +
    ant.properties
    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. If you use Eclipse, this file - is not used.
    + build settings used by Ant and also provide the location of your keystore and key alias so that + the build tools can sign your application when building in release mode. This file is integral + to the project, so maintain it in a source revision control system. If you use Eclipse, this + file is not used.
    build.xml
    The Ant build file for your project. This is only applicable for projects that - you create on the command line.
    + you build with Ant. -
    default.properties
    - -
    This file contains project settings, such as the build target. This files is integral to - the project, as such, it should be maintained in a Source Revision Control system. Do not edit - the file manually.

    Library Projects

    @@ -199,7 +209,7 @@ page.title=Managing Projects

    To download the sample applications and run them as projects in your environment, use the Android SDK and AVD Manager to download the "Samples for - SDK API 8" component into your SDK.

    + SDK API 8" (or later) component into your SDK.

    For more information and to browse the code of the samples, see the TicTacToeMain @@ -212,9 +222,10 @@ page.title=Managing Projects and, at build time, include its compiled sources in their .apk files. Multiple application projects can reference the same library project and any single application project can reference multiple library projects.

    - -

    Note: You need SDK Tools r8 or newer to fully support library projects - for all Android platform versions. You can download the tools and platforms using the + +

    Note: You need SDK Tools r14 or newer to use the new library + project feature that generates each library project into its own JAR file. + You can download the tools and platforms using the Android SDK and AVD Manager, as described in Adding SDK Components.

    @@ -246,12 +257,12 @@ page.title=Managing Projects library in the dependent application and building that application.

    When you build an application that depends on a library project, the SDK tools compile the - library and merge its sources with those in the main project, then use the result to generate - the .apk. In cases where a resource ID is defined in both the application and the - library, the tools ensure that the resource declared in the application gets priority and that - the resource in the library project is not compiled into the application .apk. - This gives your application the flexibility to either use or redefine any resource behaviors or - values that are defined in any library.

    + library into a temporary JAR file and uses it in the main project, then uses the + result to generate the .apk. In cases where a resource ID is defined in both the + application and the library, the tools ensure that the resource declared in the application gets + priority and that the resource in the library project is not compiled into the application + .apk. This gives your application the flexibility to either use or redefine any + resource behaviors or values that are defined in any library.

    To organize your code further, your application can add references to multiple library projects, then specify the relative priority of the resources in each library. This lets you @@ -259,15 +270,13 @@ page.title=Managing Projects libraries referenced from an application define the same resource ID, the tools select the resource from the library with higher priority and discard the other.

    -

    Once you have added references to library projects to your Android project, +

    Once you have added references to library projects to your Android project, you can set their relative priority. At build time, the libraries are merged with the application one at a time, starting from the lowest priority to the highest.

    -

    Note that a library project cannot itself reference another library project and that, at - build time, library projects are not merged with each other before being merged with - the application. However, note that a library can import an external library (JAR) in the - normal way.

    +

    Library projects can reference other library projects and can import an external library + (JAR) in the normal way.

    Development considerations

    @@ -283,22 +292,23 @@ page.title=Managing Projects defined in more than one project and will be merged, with the resource from the application or highest-priority library taking precedence.

    - +

  • Use prefixes to avoid resource conflicts

    To avoid resource conflicts for common resource IDs, consider using a prefix or other consistent naming scheme that is unique to the project (or is unique across all projects).

    • - +

  • You cannot export a library project to a JAR file

    -

    A library cannot be distributed as a binary file (such as a jar file). This is because the - library project is compiled by the main project to use the correct resource IDs.

    • +

    A library cannot be distributed as a binary file (such as a JAR file). This will +be added in a future + version of the SDK Tools.

  • A library project can include a JAR library

    You can develop a library project that itself includes a JAR library, however you need to manually edit the dependent application project's build path and add a path to the JAR file.

    • - +

  • A library project can depend on an external JAR library

    You can develop a library project that depends on an external library (for example, the Maps @@ -316,7 +326,7 @@ page.title=Managing Projects used by an application must be stored in the assets/ directory of the application project itself. However, resource files saved in the res/ directory are supported.

    • - +

  • Platform version must be lower than or equal to the Android project

    A library is compiled as part of the dependent application project, so the API used in the @@ -327,12 +337,12 @@ page.title=Managing Projects higher than that of the application, the application project will not compile. It is perfectly acceptable to have a library that uses the Android 1.5 API (API level 3) and that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) project, for instance.

    • - +

  • No restriction on library package names

    There is no requirement for the package name of a library to be the same as that of applications that use it.

    • - +

  • Each library project creates its own R class

    When you build the dependent application project, library projects are compiled and @@ -340,7 +350,7 @@ page.title=Managing Projects to the library's package name. The R class generated from main project and the library project is created in all the packages that are needed including the main project's package and the libraries' packages.

    • - +

  • Library project storage location

    There are no specific requirements on where you should store a library project, relative to a @@ -351,7 +361,7 @@ page.title=Managing Projects

    Test Projects

    -

    Test projects contain Android applications that you write using the +

    Test projects contain Android applications that you write using the Testing and Instrumentation framework. The framework is an extension of the JUnit test framework and adds access to Android system objects. The file structure of a test project is the same as an @@ -387,24 +397,36 @@ page.title=Managing Projects <instrumentation> element that connects the test project with the application project. -

    build.properties
    +
    project.properties
    + +
    This file contains project settings, such as the build target and links to the project being +tested. This file is integral to the project, so maintain it in a source +revision control system. To edit project properties in Eclipse, right-click the project folder +and select Properties.
    + +
    local.properties
    + +
    Customizable computer-specific properties for the build system. If you use Ant to build + the project, this contains the path to the SDK installation. Because the content of the file + is specific to the local installation of the SDK, it should not be maintained in a Source + Revision Control system. If you use Eclipse, this file is not used.
    + +
    ant.properties
    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.
    + build settings used by Ant and provide the location to your keystore and key alias, so that the + build tools can sign your application when building in release mode. This file is integral to + the project, so maintain it in a source revision control system. + If you use Eclipse, this file is not used.
    build.xml
    -
    The Ant build file for your project.
    +
    The Ant build file for your project. This is only applicable for projects that + you build with Ant.
    + -
    default.properties
    - -
    This file contains project settings, such as the build target. This files is integral to - the project, as such, it should be maintained in a Source Revision Control system. It should - never be edited manually — to edit project properties, right-click the project folder and - select "Properties".
    - For more information, see the Testing section. +

    For more information, see the Testing section.

    Testing a Library Project

    diff --git a/docs/html/guide/developing/projects/projects-cmdline.jd b/docs/html/guide/developing/projects/projects-cmdline.jd index 90f88fb43e9bb..08e0d9a16a8f3 100644 --- a/docs/html/guide/developing/projects/projects-cmdline.jd +++ b/docs/html/guide/developing/projects/projects-cmdline.jd @@ -37,8 +37,8 @@ file

    • The android tool provides you with commands to create all three types of projects. An Android project contains all of the files and resources that are needed to build a - project into an .apk file for installation. - + project into an .apk file for installation. +