Add support for subfolders in assets folders.
[android/platform/tools/build.git] / readme.md
1 ## What is this?
2
3 The official Gradle plugin to build Android applications.
4
5 ## DSL
6
7 The plugin adds several concepts to the Gradle DSL, all in the android extension:
8
9 * A _default config_. This lets you configure default values for your application.
10 * A _product flavor_. For example, a free or a paid-for flavour.
11 * A _build type_. There are 2 predefined build types, called `release` and `debug`. You can add additional build types.
12
13 If you do not define any flavors for your product, only the values from the default config are used. Flavor settings override the default config.
14
15 From this, the plugin will add the appropriate tasks to build each combination of build type and product flavor. The
16 plugin will also define the following source directories:
17
18 * `src/main/java` - Java source to be included in all application variants.
19 * `src/main/res` - Resources to be included in all application variants.
20 * `src/main/AndroidManifest.xml' - The application manifest (currently shared by all application variants).
21 * `src/$BuildType/java` - Java source to be included in all application variants with the given build type.
22 * `src/$BuildType/res` - Java source to be included in all application variants with the given build type.
23 * `src/$ProductFlavor/java` - Resources to be included in all application variants with the given product flavor.
24 * `src/$ProductFlavor/res` - Resources to be included in all application variants with the given product flavor.
25 * `src/test/java` - Test source to be included in all test applications.
26 * `src/test$ProductFlavor/java` - Test source to be include for the test application for the given product flavor.
27
28 You can configure these locations by configuring the associated source set provided by the android extension.
29
30 Compile time dependencies are declared in the usual way.
31
32 Have a look at the `tests/basic/build.gradle` build file and other projects in tests `customized/build.gradle` to see the DSL in action.
33
34 ### Configuration options
35
36 * `android.target` - required.
37 * `android.defaultConfig.versionCode` - defaults to that specified in `src/main/AndroidManifest.xml`
38 * `android.defaultConfig.versionName` - defaults to that specified in `src/main/AndroidManifest.xml`
39 * `android.productFlavors.$flavor.packageName` - defaults to that specified in `src/main/AndroidManifest.xml`
40 * `android.productFlavors.$flavor.versionCode` - defaults to `${android.defaultConfig.versionCode}`
41 * `android.productFlavors.$flavor.versionName` - defaults to `${android.defaultConfig.versionName}`
42 * `android.buildTypes.$type.zipAlign` - defaults to `true` for `release` and `false` for `debug`
43 * `android.sourceSets.main.java.srcDirs` - defaults to `src/main/java`
44 * `android.sourceSets.main.resources.srcDirs` - defaults to `src/main/res`
45 * `android.sourceSets.$flavor.java.srcDirs` - defaults to `src/$flavor/java`
46 * `android.sourceSets.$flavor.resources.srcDirs` - defaults to `src/$flavor/res`
47 * `android.sourceSets.$buildType.java.srcDirs` - defaults to `src/$buildType/java`
48 * `android.sourceSets.$buildType.resources.srcDirs` - defaults to `src/$buildType/res`
49 * `android.sourceSets.test.java.srcDirs` - defaults to `src/test/java`
50 * `android.sourceSets.test$Flavor.java.srcDirs` - defaults to `src/test$Flavor/java`
51 * `dependencies.compile` - compile time dependencies for all applications.
52
53 ## Contents
54
55 The source tree contains the following:
56
57 * The `builder` directory contains the builder library.
58 * The `gradle` directory contains the plugin implementation.
59 * The `tests` directory contains various test applications used both as samples and tests by the plugin build system.
60
61 ## Usage
62
63 To build the plugin, run `./gradlew uploadArchives`
64
65 To build the plugin for release, removing the SNAPSHOT from the version, run `./gradlew --init-script release.gradle <tasks>`
66
67 To import the plugin into the IDE, run `./gradlew idea` or `./gradlew eclipse`.
68
69 To build a test application:
70 1. cd into the root directory of the test application.
71 2. Edit the `local.properties` file to point at your local install of the Android SDK. Normally, these files would not
72 be checked into source control, but would be generated when the project is bootstrapped.
73 3. Run `../../gradlew tasks` to see the tasks that are available.
74
75 You can also run these tasks:
76
77 * `assemble` - builds all combinations of build type and product flavor
78 * `assemble$BuildType` - build all flavors for the given build type.
79 * `assemble$ProductFlavor` - build all build types for the given product flavor.
80 * `assemble$ProductFlavor$BuildType` - build the given application variant.
81 * `install$ProductFlavor$BuildType` - build and install the given application variant.
82
83 ## Implementation
84
85 For each variant (product-flavor, build-type):
86
87 * Generates resource source files into `build/source` from resource directories (main-source-set, product-flavor-source-set, build-type-source-set)
88 * Compile source files (main-source-set, product-flavor-source-set, build-type-source-set, generated-source).
89 * Converts the bytecode into `build/libs`
90 * Crunches resources in `build/resources`
91 * Packages the resource into `build/libs`
92 * Assembles the application package into `build/libs`.
93
94 Some other notes:
95 * No support for running ProGuard.