Rich Slogar | 4083327 | 2014-11-06 17:15:28 -0800 | [diff] [blame] | 1 | page.title=Android Plug-in for Gradle |
| 2 | |
| 3 | @jd:body |
| 4 | |
| 5 | <div id="qv-wrapper"> |
| 6 | <div id="qv"> |
| 7 | <h2>In this document</h2> |
| 8 | <ol> |
| 9 | <li><a href="#workBuildVariants">Work with build variants</a></li> |
| 10 | </ol> |
| 11 | |
| 12 | |
| 13 | <h2>See also</h2> |
| 14 | <ul> |
| 15 | <li><a href="{@docRoot}sdk/installing/studio-build.html"> |
| 16 | Build System Overview</a></li> |
| 17 | <li><a href="{@docRoot}tools/building/index.html"> |
| 18 | Buidling and Running</a></li> |
| 19 | <li><a href="{@docRoot}tools/building/building-studio.html"> |
| 20 | Building and Running from Android Studio</a></li> |
| 21 | </ul> |
| 22 | |
| 23 | <h2>Download</h2> |
| 24 | <div class="download-box"> |
| 25 | <a href="{@docRoot}shareables/sdk-tools/android-gradle-plugin-dsl.zip" |
Rich Slogar | c6127b0 | 2014-12-18 14:41:25 -0800 | [diff] [blame] | 26 | class="button">Plugin Language Reference</a> |
Rich Slogar | 4083327 | 2014-11-06 17:15:28 -0800 | [diff] [blame] | 27 | <p class="filename">android-gradle-plugin-dsl.zip</p> |
| 28 | </div> |
| 29 | |
| 30 | </div> |
| 31 | </div> |
| 32 | |
| 33 | <p>The Android build system consists of an Android plugin for <em>Gradle</em>. |
| 34 | <a href="http://www.gradle.org/">Gradle</a> is an advanced build toolkit that manages |
| 35 | dependencies and allows you to define custom build logic. Android Studio uses a Gradle wrapper |
| 36 | to fully integrate the Android plugin for Gradle. The Android plugin for Gradle also runs |
| 37 | independent of Android Studio. This means that you can build your Android apps from which Android |
| 38 | Studio and from the command line on your machine or on machines where Android Studio is not installed |
| 39 | (such as continuous integration servers).</p> |
| 40 | |
| 41 | <p>The output of the build is the same whether you are building a project from the command line, |
| 42 | on a remote machine, or using Android Studio.</p> |
| 43 | |
| 44 | <h2 id="buildConf">Build configuration</h2> |
| 45 | |
| 46 | <p>The build configuration for your project is defined inside <code>build.gradle</code> files, |
| 47 | which are plain text files that use the syntax and options from Gradle and the Android plugin |
| 48 | to configure the following aspects of your build:</p> |
| 49 | |
| 50 | <ul> |
| 51 | <li><em>Build variants</em>. The build system can generate multiple APKs with different |
| 52 | product and build configurations for the same module. This is useful when you want to |
| 53 | build different versions of your application without having to create a separate projects |
| 54 | or modules for each version.</li> |
| 55 | <li><em>Dependencies</em>. The build system manages project dependencies and supports |
| 56 | dependencies from your local filesystem and from remote repositories. This prevents you |
| 57 | from having to search, download, and copy binary packages for your dependencies into your |
| 58 | project directory.</li> |
| 59 | <li><em>Manifest entries</em>. The build system enables you to specify values for some |
| 60 | elements of the manifest file in the build variant configuration. These build values |
| 61 | override the existing values in the manifest file. This is useful if you want to generate |
| 62 | multiple APKs for your modules where each of the <code>apk</code> files has a different |
| 63 | application name, minimum SDK version, or target SDK version. When multiple manifests are |
| 64 | present, manifest settings are merged in priority of buildType and productFlavor, |
| 65 | <code>/main</code> manifest, and the library manifests.</li> |
| 66 | <li><em>Signing</em>. The build system enables you to specify signing settings in the build |
| 67 | configuration, and it can sign your APKs during the build process.</li> |
| 68 | <li><em>ProGuard</em>. The build system enables you to specify a different |
| 69 | <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> rules |
| 70 | file for each build variant. The build system can run ProGuard to obfuscate your classes |
| 71 | during the build process.</li> |
| 72 | <li><em>Testing</em>. For most templates, the build system creates a test directory, |
| 73 | <em>androidTest</em> and generates a test APK from the test sources in your project, so |
| 74 | you do not have to create a separate test project. The build system can also run your tests |
| 75 | during the build process.</li> |
| 76 | </ul> |
| 77 | |
| 78 | <p>Gradle build files use Domain Specific Language (DSL) to describe and manipulate the build logic |
| 79 | through <em>Groovy</em> syntax. <a href="http://groovy.codehaus.org/">Groovy</a> is a dynamic |
| 80 | language that you can use to define custom build logic and to interact with the Android-specific |
| 81 | elements provided by the Android plugin for Gradle.</p> |
| 82 | |
| 83 | <h2 id="buildConv">Build by convention</h2> |
| 84 | |
| 85 | <p>The Android Studio build system assumes <em>sensible defaults</em> for the project structure |
| 86 | and other build options. If your project adheres to these conventions, your Gradle build files are |
| 87 | very simple. When some of these conventions do not apply to your project, the flexibility of the |
| 88 | build system allows you to configure almost every aspect of the build process. For example, if |
| 89 | you need to replace the default source folders in your module directories, you can configure a new |
| 90 | directory structure in the module's build file. </p> |
| 91 | |
| 92 | <h2 id="projectModules">Projects and modules build settings</h2> |
| 93 | |
| 94 | <p>A <em>project</em> in Android Studio represents the top-level Android development structure. |
| 95 | Android Studio projects contain project files and one or more application modules. A |
| 96 | <em>module</em> is a component of your app that you can build, test, or debug independently. |
| 97 | Modules contain the source code and resources for your apps. Android Studio projects can contain |
| 98 | several kinds of modules:</p> |
| 99 | |
| 100 | <ul> |
| 101 | <li><em>Android application modules</em> contain application (mobile, TV, Wear, Glass) code and |
| 102 | may depend on library modules, although many Android apps consists of only one application |
| 103 | module. The build system generates APK packages for application modules. </li> |
| 104 | <li><em>Android library modules</em> contain reusable Android-specific code and resources. |
| 105 | The build system generates an AAR (Android ARchive) package for library modules.</li> |
| 106 | <li><em>App Engine modules</em> contain code and resources for App Engine integration.</li> |
| 107 | <li><em>Java library modules</em> contain reusable code. The build system generates a |
| 108 | JAR package for Java library modules.</li> |
| 109 | </ul> |
| 110 | |
| 111 | <p>Android Studio projects contain a top-level project Gradle build file that allows you to add the |
| 112 | configuration options common to all application modules in the project. Each application module |
| 113 | also has its own build.gradle file for build settings specific to that module.</p> |
| 114 | |
| 115 | <h3>Project Build File</h3> |
| 116 | <p>By default, the project-level Gradle file uses <em>buildscript</em> to define the Gradle |
| 117 | <em>repositories</em> and <em>dependencies</em>. This allows different projects to use different |
| 118 | Gradle versions. Supported repositories include JCenter, Maven Central, or Ivy. This example |
| 119 | declares that the build script uses the JCenter repository and a classpath dependency artifact |
Rich Slogar | 7ddb126 | 2014-12-17 17:05:41 -0800 | [diff] [blame] | 120 | that contains the Android plugin for Gradle version 1.0.1. |
Rich Slogar | 4083327 | 2014-11-06 17:15:28 -0800 | [diff] [blame] | 121 | </p> |
| 122 | <p> |
| 123 | <pre> |
| 124 | buildscript { |
| 125 | repositories { |
| 126 | jcenter() |
| 127 | } |
| 128 | dependencies { |
Rich Slogar | 7ddb126 | 2014-12-17 17:05:41 -0800 | [diff] [blame] | 129 | classpath 'com.android.tools.build:gradle:1.0.1' |
Rich Slogar | 4083327 | 2014-11-06 17:15:28 -0800 | [diff] [blame] | 130 | |
| 131 | // NOTE: Do not place your application dependencies here: they belong |
| 132 | // in the individual module build.gradle files |
| 133 | } |
| 134 | } |
| 135 | |
| 136 | allprojects { |
| 137 | repositories { |
| 138 | jcenter() |
| 139 | } |
| 140 | } |
| 141 | </pre> |
| 142 | |
| 143 | <p class="note"><strong>Note:</strong> The SDK location for the Android Studio project is defined in |
| 144 | the <em>local.properties</em> file in the <code>sdk.dir<sdk location></code> setting or through an |
| 145 | <code>ANDROID_HOME</code> environment variable.</p> |
| 146 | |
| 147 | <h3>Module Build File</h3> |
| 148 | <p>The application module Gradle build file allows you to configure module build settings, |
| 149 | including overriding the <code>src/main</code> manifest settings and setting custom packaging |
| 150 | options. </p> |
| 151 | |
| 152 | <ul> |
| 153 | <li>android settings </li> |
| 154 | <ul> |
| 155 | <li>compileSdkVersion</li> |
| 156 | <li>buildToolsVersion</li> |
| 157 | </ul> |
| 158 | |
| 159 | <li>defaultConfig and productFlavors </li> |
| 160 | <ul> |
| 161 | <li>manifest properties such as applicationId, minSdkVersion, targetSdkVersion, and test |
| 162 | information</li> |
| 163 | </ul> |
| 164 | |
| 165 | <li>buildTypes</li> |
| 166 | <ul> |
| 167 | <li>build properties such as debuggable, ProGuard enabling, debug signing, version name |
| 168 | suffix and testinformation</li> |
| 169 | </ul> |
| 170 | |
| 171 | <li>dependencies</li> |
| 172 | </ul> |
| 173 | |
| 174 | <p>This example applies the Android plugin, uses the default configuration to override several |
| 175 | manifest properties, creates two build types: release and debug, and declares several dependencies. |
| 176 | </p> |
| 177 | |
| 178 | <pre> |
| 179 | apply plugin: 'com.android.application' |
| 180 | |
| 181 | android { |
| 182 | compileSdkVersion 20 |
| 183 | buildToolsVersion "20.0.0" |
| 184 | |
| 185 | defaultConfig { |
| 186 | applicationId "com.mycompany.myapplication" |
| 187 | minSdkVersion 13 |
| 188 | targetSdkVersion 20 |
| 189 | versionCode 1 |
| 190 | versionName "1.0" |
| 191 | } |
| 192 | |
| 193 | buildTypes { |
| 194 | release { |
| 195 | minifyEnabled false |
| 196 | proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' |
| 197 | } |
| 198 | debug { |
| 199 | debuggable true |
| 200 | } |
| 201 | } |
| 202 | } |
| 203 | |
| 204 | dependencies { |
| 205 | compile fileTree(dir: 'libs', include: ['*.jar']) |
| 206 | compile 'com.android.support:appcompat-v7:20.0.0' |
| 207 | compile project(path: ':app2, configuration: 'android-endpoints') |
| 208 | } |
| 209 | </pre> |
| 210 | |
| 211 | |
| 212 | <p class="note"><strong>Note:</strong> You can inject custom build logic for property values defined |
| 213 | by a function that gets called by the property, for example: |
| 214 | <pre> |
| 215 | def computeVersionName() { |
| 216 | ... |
| 217 | } |
| 218 | |
| 219 | android { |
| 220 | defaultConfig { |
| 221 | versionName computeVersionName() |
| 222 | ... |
| 223 | } |
| 224 | } |
| 225 | </pre> |
| 226 | </p> |
| 227 | |
| 228 | |
| 229 | |
| 230 | <h2 id="dependencies">Dependencies</h2> |
| 231 | |
| 232 | <p>The Android Studio build system manages project dependencies and supports module dependencies, |
| 233 | local binary dependencies, and remote binary dependencies.</p> |
| 234 | |
| 235 | <dl> |
| 236 | <dt><em>Module Dependencies</em></dt> |
| 237 | <dd><p>An application module can include in its build file a list of other modules it depends on. |
| 238 | When you build this module, the build system assembles and includes the required |
| 239 | modules.</p></dd> |
| 240 | <dt><em>Local Dependencies</em></dt> |
| 241 | <dd><p>If you have binary archives in your local filesystem that a module depends on, such as |
| 242 | JAR files, you can declare these dependencies in the build file for that module.</p></dd> |
| 243 | <dt><em>Remote Dependencies</em></dt> |
| 244 | <dd><p>When some of your dependencies are available in a remote repository, you do not have |
| 245 | to download them and copy them into your project. The Android Studio build system supports |
| 246 | remote dependencies from repositories, such as <a href="http://maven.apache.org/">Maven</a>, |
| 247 | and dependency managers, such as <a href="http://ant.apache.org/ivy/">Ivy</a>. </p> |
| 248 | <p>Many popular software libraries and tools are available in public Maven repositories. |
| 249 | For these dependencies you only have to specify their Maven coordinates, which uniquely |
| 250 | identify each element in a remote repository. The format for Maven coordinates used in the |
| 251 | build system is <code>group:name:version</code>. For example, the Maven coordinates for |
| 252 | version 16.0.1 of the Google Guava libraries are |
| 253 | <code>com.google.guava:guava:16.0.1</code>.</p> |
| 254 | <p>The <a href="http://search.maven.org">Maven Central Repository</a> is widely used to |
| 255 | distribute many libraries and tools.</p> |
| 256 | </dd> |
| 257 | </dl> |
| 258 | |
| 259 | <h2 id="buildTasks">Build tasks</h2> |
| 260 | |
| 261 | <p>The Android Studio build system defines a hierarchical set of build tasks: the top-level or |
| 262 | anchor tasks invoke dependent tasks to produce their collective build outcomes. The top-level build |
| 263 | tasks are:</p> |
| 264 | |
| 265 | <dl> |
| 266 | <dt>assemble </dt> |
| 267 | <dd><p>Builds the project output. </p></dd> |
| 268 | <dt>check </dt> |
| 269 | <dd><p>Runs checks and tests.</p></dd> |
| 270 | <dt>build </dt> |
| 271 | <dd><p>Runs both assemble and check. </p></dd> |
| 272 | <dt>clean </dt> |
| 273 | <dd><p>Performs the clean.</p></dd> |
| 274 | </dl> |
| 275 | |
| 276 | <p>The Android plugin provides additional tasks for <em>connectedCheck</em> and <em>deviceCheck</em> |
| 277 | for checks run on connected, emulated, and remote devices. Gradle tasks can be viewed by clicking |
| 278 | the Gradle tab</a> in the right margin. |
| 279 | <img src="{@docRoot}images/tools/studio-gradle-tab.png"></p> |
| 280 | <p class="img-caption"><strong>Figure 1:</strong> Gradle tab</p> |
| 281 | |
| 282 | <p>Running a top-level task, runs all the dependent tasks. For example, the <em>assemble</em> task |
| 283 | has dependent tasks for <em>assembleDebug</em> and <em>assembleRelease</em> to make the debug and |
| 284 | release APKs. The <em>assemble</em> task depends on these tasks so calling it builds both APKs. |
| 285 | These tasks can also be called independently to build the debug or release APK separately. </p> |
| 286 | |
| 287 | <p>You can view the list of available tasks and invoke any task from Android Studio and from |
| 288 | the command line, as described in |
| 289 | <a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android Studio</a> |
| 290 | and <a href="{@docRoot}tools/building/building-cmdline.html">Build the project from |
| 291 | the command line</a>.</p> |
| 292 | |
| 293 | <h2 id="gradleWrapper">The Gradle wrapper</h2> |
| 294 | |
| 295 | <p>Android Studio projects contain the <em>Gradle wrapper</em>, which consists of:</p> |
| 296 | |
| 297 | <ul> |
| 298 | <li>A JAR file</li> |
| 299 | <li>A properties file</li> |
| 300 | <li>A shell script for Windows platforms</li> |
| 301 | <li>A shell script for Mac and Linux platforms</li> |
| 302 | </ul> |
| 303 | |
| 304 | <p class="note"><strong>Note:</strong> You should submit all of these files to your source |
| 305 | control system.</p> |
| 306 | |
| 307 | <p>Using the Gradle wrapper (instead of the local Gradle installation) ensures that |
| 308 | you always run the version of Gradle defined in the <em>local.properties</em> file. To configure your |
| 309 | project to use a newer version of Gradle, edit the properties file and specify the new version there. |
| 310 | </p> |
| 311 | |
| 312 | <p>Android Studio reads the properties file from the Gradle wrapper directory inside your project |
| 313 | and runs the wrapper from this directory, so you can seamlessly work with multiple projects |
| 314 | that require different versions of Gradle.</p> |
| 315 | |
| 316 | <p class="note"><strong>Note:</strong> Android Studio does not use the shell scripts, so any |
| 317 | changes you make to them won't work when building from the IDE. You should define your custom |
| 318 | logic inside Gradle build files instead.</p> |
| 319 | |
| 320 | <p>You can run the shell scripts to build your project from the command line on your development |
| 321 | machine and on other machines where Android Studio is not installed.</p> |
| 322 | |
Rich Slogar | dcfe5b6 | 2014-12-10 17:10:55 -0800 | [diff] [blame] | 323 | <p class="caution"><strong>Caution:</strong> When you create a project, only use the Gradle wrapper |
Rich Slogar | 6392487 | 2015-01-23 09:56:50 -0800 | [diff] [blame] | 324 | scripts and JAR from a trusted source, such as those generated by Android Studio. </p> |
Rich Slogar | dcfe5b6 | 2014-12-10 17:10:55 -0800 | [diff] [blame] | 325 | |
Rich Slogar | 4083327 | 2014-11-06 17:15:28 -0800 | [diff] [blame] | 326 | |
| 327 | <h2 id="buildVariants"> Build variants</h2> |
| 328 | |
| 329 | <p>Each version of your app is represented in the build system by a <em>build variant</em>. |
| 330 | Build variants are combinations of product flavors and build types. Product flavors represent |
| 331 | product build versions of an app, such as free and paid. Build types represent the build |
| 332 | packaging versions generated for each app package, such as debug and release. The build system |
| 333 | generates APKs for each combination of product flavor and build type.</p> |
| 334 | |
| 335 | <p>By default, Android Studio defines default configuration settings, <code>defaultConfig</code> in |
| 336 | the build.gradle file, and two build types (<em>debug</em> and <em>release</em>). This creates two |
| 337 | build variants, debug and release, and the build system generates an |
| 338 | APK for each variant. </p> |
| 339 | |
| 340 | <p>Adding two product flavors, <em>demo</em> and <em>full</em> along |
| 341 | with the default build types <em>debug</em> and <em>release</em> generates four build variants, |
| 342 | each with its own customized configuration:</p> |
| 343 | |
| 344 | <ul> |
| 345 | <li>demoDebug</li> |
| 346 | <li>demoRelease</li> |
| 347 | <li>fullDebug</li> |
| 348 | <li>fullRelease</li> |
| 349 | </ul> |
| 350 | |
| 351 | Resources are merged across the multiple Android application sources: |
| 352 | <ul> |
| 353 | <li>Build variants based on the buildType, and productFlavor build settings</li> |
| 354 | <li>The main sourceSet, generally located in src/main/res</li> |
| 355 | <li>Library Project dependencies, which contribute resources through the res entry in their aar |
| 356 | bundle.</li> |
| 357 | </ul> |
| 358 | |
| 359 | <p>The priority of the merge order from lowest to highest is libraries/dependencies -> main src -> |
| 360 | productFlavor -> buildType.</p> |
| 361 | |
| 362 | |
| 363 | <p>Some projects have complex combinations of features along more than one dimension, but they |
| 364 | still represent the same app. For example, in addition to having a demo and a full version of the |
| 365 | app, some games may contain binaries specific to a particular CPU/ABI. The flexibility of |
| 366 | the build system makes it possible to generate the following build variants for such a project:</p> |
| 367 | |
| 368 | <ul> |
| 369 | <li>x86-demoDebug</li> |
| 370 | <li>x86-demoRelease</li> |
| 371 | <li>x86-fullDebug</li> |
| 372 | <li>x86-fullRelease</li> |
| 373 | <li>arm-demoDebug</li> |
| 374 | <li>arm-demoRelease</li> |
| 375 | <li>arm-fullDebug</li> |
| 376 | <li>arm-fullRelease</li> |
| 377 | <li>mips-demoDebug</li> |
| 378 | <li>mips-demoRelease</li> |
| 379 | <li>mips-fullDebug</li> |
| 380 | <li>mips-fullRelease</li> |
| 381 | </ul> |
| 382 | |
| 383 | <p>This project would consist of two build types (<em>debug</em> and <em>release</em>) |
| 384 | and two <em>dimensions</em> of product flavors, one for app type (demo or full) and one for |
| 385 | CPU/ABI (x86, ARM, or MIPS). </p> |
| 386 | |
| 387 | |
| 388 | <h3>Source directories</h3> |
| 389 | |
| 390 | <p>To build each version of your app, the build system combines source code and |
| 391 | resources from:</p> |
| 392 | |
| 393 | <ul> |
| 394 | <li><code>src/main/</code> - the main source directory (the default configuration common to all |
| 395 | variants)</li> |
| 396 | <li><code>src/<buildType>/</code> - the <buildType> source directory</li> |
| 397 | <li><code>src/<productFlavor>/</code> - the <productFlavor> source directory</li> |
| 398 | </ul> |
| 399 | |
| 400 | <p class="note"><strong>Note:</strong> The build type and product flavor source directories are optional, |
| 401 | as Android Studio does not create these directories for you. You should create these directories |
| 402 | as you add build types and product flavors to the build configuration files. The build system does not |
| 403 | use these directories if they are not present.</p> |
| 404 | |
| 405 | <p>For projects that do not define any flavors, the build system uses the <em>defaultConfig</em> |
| 406 | settings, the main app directory and the default build type directories. For example, to generate |
| 407 | the default <em>debug</em> and <em>release</em> build variants in projects with no product flavors, |
| 408 | the build system uses:</p> |
| 409 | <ul> |
| 410 | <li><code>src/main/</code> (default configuration)</li> |
| 411 | <li><code>src/release/</code> (build type)</li> |
| 412 | <li><code>src/debug/</code> (build type)</li> |
| 413 | </ul> |
| 414 | |
| 415 | <p>For projects that define a set of product flavors, the build system merges the build type, product |
| 416 | flavor and main source directories. For example, to generate the <em>full-debug</em> build variant, |
| 417 | the build system merges the build type, product flavor and main directories:</p> |
| 418 | <ul> |
| 419 | <li><code>src/main/</code> (default configuration)</li> |
| 420 | <li><code>src/debug/</code> (build type)</li> |
| 421 | <li><code>src/full/</code> (flavor)</li> |
| 422 | </ul> |
| 423 | |
| 424 | <p>For projects that use flavor dimensions, the build system merges one flavor source directory per |
| 425 | dimension. For example, to generate the <em>arm-demo-release</em> build variant, the build system |
| 426 | merges:</p> |
| 427 | <ul> |
| 428 | <li><code>src/main/</code> (default configuration)</li> |
| 429 | <li><code>src/release/</code> (build type)</li> |
| 430 | <li><code>src/demo/</code> (flavor - app type dimension)</li> |
| 431 | <li><code>src/arm/</code> (flavor - ABI dimension)</li> |
| 432 | </ul> |
| 433 | |
| 434 | |
| 435 | <p>The source code from these directories is used together to generate the output for a build |
| 436 | variant. You can have classes with the same name in different directories as long as those |
| 437 | directories are not used together in the same variant. </p> |
| 438 | |
| 439 | <p>The build system also merges all the manifests into a single manifest, so each build variant |
| 440 | can define different components or permissions in the final manifest. The manifest merge priority |
| 441 | from lowest to highest is libraries/dependencies -> main src -> productFlavor -> buildType. </p> |
| 442 | |
| 443 | <p>The build system merges all the resources from the all the source directories. If different |
| 444 | folders contain resources with the same name for a build variant, the priority order is the |
| 445 | following: build type resources override those from the product flavor, which override the |
| 446 | resources in the main source directory, which override those in any libraries.</p> |
| 447 | |
| 448 | <p class="note"><strong>Note:</strong> Build variants enable you to reuse common activities, |
| 449 | application logic, and resources across different versions of your app.</p> |
| 450 | |
| 451 | |