readme.md
1## What is this?
2
3A prototype Gradle plugin to build Android applications. This is intended to be used to explore how such a plugin
4would look and to develop some ideas about how such a plugin would be implemented.
5
6The plugin is functional, if a bit rough, and can generate packaged applications ready to install.
7
8## DSL
9
10The plugin adds 2 concepts to the Gradle DSL:
11
12* A _build type_. There are 2 predefined build types, called `release` and `debug`. You can add additional build types.
13* A _product flavor_. For example, a free or a paid-for flavour.
14
15If you do not define any flavors for your product, a default flavor called `main` is added.
16
17From this, the plugin will add the appropriate tasks to build each combination of build type and product flavor. The
18plugin will also define the following source directories:
19
20* `src/main/java` - Java source to be included in all application variants.
21* `src/main/res` - Resources to be included in all application variants.
22* `src/main/AndroidManifest.xml' - The application manifest (currently shared by all application variants).
23* `src/$BuildType/java` - Java source to be included in all application variants with the given build type.
24* `src/$BuildType/res` - Java source to be included in all application variants with the given build type.
25* `src/$ProductFlavor/java` - Resources to be included in all application variants with the given product flavor.
26* `src/$ProductFlavor/res` - Resources to be included in all application variants with the given product flavor.
27* `src/test/java` - Test source to be included in all test applications.
28* `src/test$ProductFlavor/java` - Test source to be include for the test application for the given product flavor.
29
30You can configure these locations by configuring the associated source set.
31
32Compile time dependencies are declared in the usual way.
33
34Have a look at the `basic/build.gradle` and `customized/build.gradle` build files to see the DSL in action.
35
36### Configuration options
37
38* `android.packageName` - defaults to that specified in `src/main/AndroidManifest.xml`
39* `android.versionCode` - defaults to that specified in `src/main/AndroidManifest.xml`
40* `android.versionName` - defaults to that specified in `src/main/AndroidManifest.xml`
41* `android.target` - defaults to `android-16`.
42* `android.productFlavors.$flavor.packageName` - defaults to `${android.packageName}`
43* `android.productFlavors.$flavor.versionCode` - defaults to `${android.versionCode}`
44* `android.productFlavors.$flavor.versionName` - defaults to `${android.versionName}`
45* `android.buildTypes.$type.zipAlign` - defaults to `true` for `release` and `false` for `debug`
46* `sourceSets.main.java.srcDirs` - defaults to `src/main/java`
47* `sourceSets.main.resources.srcDirs` - defaults to `src/main/res`
48* `sourceSets.$flavor.java.srcDirs` - defaults to `src/$flavor/java`
49* `sourceSets.$flavor.resources.srcDirs` - defaults to `src/$flavor/res`
50* `sourceSets.$buildType.java.srcDirs` - defaults to `src/$buildType/java`
51* `sourceSets.$buildType.resources.srcDirs` - defaults to `src/$buildType/res`
52* `sourceSets.test.java.srcDirs` - defaults to `src/test/java`
53* `sourceSets.test$Flavor.java.srcDirs` - defaults to `src/test$Flavor/java`
54* `dependencies.compile` - compile time dependencies for all applications.
55
56## Contents
57
58The source tree contains the following:
59
60* The `gradle` directory contains the plugin implementation.
61* The `testapps/basic` directory contains a simple application that follows the conventions
62* The `testapps/customized` directory contains an application with some custom build types, product flavors and other
63customizations.
64* The `testapps/multiproject` directory contains an application composed from several Gradle projects.
65
66## Usage
67
68To build the plugin, run `./gradlew uploadArchives`
69
70To import the plugin into the IDE, run `./gradlew idea` or `./gradlew eclipse`.
71
72To build a test application:
731. cd into the root directory of the test application.
742. Edit the `local.properties` file to point at your local install of the Android SDK. Normally, these files would not
75be checked into source control, but would be generated when the project is bootstrapped.
763. Run `../../gradlew tasks` to see the tasks that are available.
77
78You can also run these tasks:
79
80* `assemble` - builds all combinations of build type and product flavor
81* `assemble$BuildType` - build all flavors for the given build type.
82* `assemble$ProductFlavor` - build all build types for the given product flavor.
83* `assemble$ProductFlavor$BuildType` - build the given application variant.
84* `install$ProductFlavor$BuildType` - build and install the given application variant.
85
86## Implementation
87
88For each variant (product-flavor, build-type):
89
90* Generates resource source files into `build/source` from resource directories (main-source-set, product-flavor-source-set, build-type-source-set)
91* Compile source files (main-source-set, product-flavor-source-set, build-type-source-set, generated-source).
92* Converts the bytecode into `build/libs`
93* Crunches resources in `build/resources`
94* Packages the resource into `build/libs`
95* Assembles the application package into `build/libs`.
96
97Some other notes:
98* Uses `sourceSets.main.compileClasspath` as the compile classpath for each variant. Could potentially also include
99`sourceSets.$BuildType.compileClasspath` and `sourceSets.$ProductFlavor.compileClasspath` as well.
100* Currently, the plugin signs all applications using the debug key.
101* No support for building test applications.
102* No support for building library projects.
103* No support for running ProGuard.
104