diff options
Diffstat (limited to 'docs/html/tools/building/configuring-gradle.jd')
| -rw-r--r-- | docs/html/tools/building/configuring-gradle.jd | 478 |
1 files changed, 478 insertions, 0 deletions
diff --git a/docs/html/tools/building/configuring-gradle.jd b/docs/html/tools/building/configuring-gradle.jd new file mode 100644 index 0000000..2e15473 --- /dev/null +++ b/docs/html/tools/building/configuring-gradle.jd @@ -0,0 +1,478 @@ +page.title=Configuring Gradle Builds + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#buildFileBasics">Build Configuration Basics</a> + <ol> + <li><a href="#buildFileBasics">Declare dependencies</a></li> + <li><a href="#buildFileBasics">Run ProGuard</a></li> + <li><a href="#configureSigning">Configure signing settings</a></li> + </ol> + </li> + + + <li><a href="#workBuildVariants">Work with build variants</a></li> +</ol> + + +<h2>See also</h2> +<ul> +<li><a href="{@docRoot}tools/building/plugin-for-gradle.html"> +Android Plugin for Gradle</a></li> +</ul> +</div> +</div> + + +<p>This section builds on the +<a href="{@docRoot}sdk/installing/studio-build.html">Build System Overview</a> and +<a href="{@docRoot}tools/building/building-studio.html">Build and Running from Android Studio</a> +to show you how to use build variants based on product flavors and build types.</p> + + +<h2 id="buildFileBasics">Build Configuration Basics</h2> + +<p>Android Studio projects contain a top-level build file and a build file for each module. The +build files are called <code>build.gradle</code>, and they are plain text files that use +<a href="http://groovy.codehaus.org">Groovy</a> syntax to configure the build with the elements +provided by the Android plugin for Gradle. In most cases, you only need to edit the build files +at the module level. For example, the build file for the app module in the +<code>BuildSystemExample</code> project looks like this:</p> + +<pre> +apply plugin: 'android' + +android { + compileSdkVersion 19 + buildToolsVersion "19.0.0" + + defaultConfig { + minSdkVersion 8 + targetSdkVersion 19 + versionCode 1 + versionName "1.0" + } + buildTypes { + release { + minifyEnabled true + proguardFiles getDefaultProguardFile('proguard-android.txt'), \ + 'proguard-rules.txt' + } + } +} + +dependencies { + compile project(":lib") + compile 'com.android.support:appcompat-v7:19.0.1' + compile fileTree(dir: 'libs', include: ['*.jar']) +} +</pre> + +<p><code>apply plugin: 'android'</code> applies the Android plugin for Gradle to this build. +This adds Android-specific build tasks to the top-level build tasks and makes the +<code>android {...}</code> element available to specify Android-specific build options.</p> + +<p><code>android {...}</code> configures all the Android-specific build options:</p> + +<ul> + <li>The <code>compileSdkVersion</code> property specifies the compilation target.</li> + <li><p>The <code>buildToolsVersion</code> property specifies what version of the build tools + to use. To install several versions of the build tools, use the SDK Manager.</p> + <p class="note"><strong>Note:</strong> Always use a build tools version whose major + revision number is higher or equal to that of your compilation target and target SDK.</p> + </li> + <li><p>The <code>defaultConfig</code> element configures core settings and + entries in the manifest file (<code>AndroidManifest.xml</code>) dynamically from the + build system. The values in <code>defaultConfig</code> override those in the manifest + file.</p> + <p>The configuration specified in the <code>defaultConfig</code> element applies + to all build variants, unless the configuration for a build variant overrides some + of these values.</p> + </li> + <li>The <code>buildTypes</code> element controls how to build and package your app. + By default, the build system defines two build types: <em>debug</em> and + <em>release</em>. The debug build type includes debugging symbols and is signed with + the debug key. The release build type is not signed by default. + In this example the build file configures the release version to use + ProGuard.</li> +</ul> + +<p>The <code>dependencies</code> element is outside and after the <code>android</code> element. +This element declares the dependencies for this module. Dependencies are covered in the following +sections.</p> + +<p class="note"><strong>Note:</strong> When you make changes to the build files in your project, +Android Studio requires a project sync to import the build configuration changes. Click +<strong>Sync Now</strong> on the yellow notification bar that appears for Android Studio +to import the changes.</p> + +<img src="{@docRoot}images/tools/as-gradlesync.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> Sync the project in Android Studio.</p> + +<h3 id="declareDeps">Declare dependencies</h3> + +<p>The <code>app</code> module in this example declares three +dependencies:</p> + +<pre> +... +dependencies { + // Module dependency + compile project(":lib") + + // Remote binary dependency + compile 'com.android.support:appcompat-v7:19.0.1' + + // Local binary dependency + compile fileTree(dir: 'libs', include: ['*.jar']) +} +</pre> + +<p>Each of these dependencies is described below. The build system adds all the +<code>compile</code> dependencies to the compilation classpath and includes them in the final +package.</p> + +<h4>Module dependencies</h4> + +<p>The <code>app</code> module depends on the <code>lib</code> module, because +<code>MainActivity</code> launches <code>LibActivity1</code> as described in +<a href="#openActFromLib">Open an Activity from a Library Module</a>.</p> + +<p><code>compile project(":lib")</code> declares a dependency on the <code>lib</code> +module of <code>BuildSystemExample</code>. When you build the <code>app</code> module, +the build system assembles and includes the <code>lib</code> module.</p> + +<h4>Remote binary dependencies</h4> + +<p>The <code>app</code> and <code>lib</code> modules both use the <code>ActionBarActivity</code> +class from the Android Support Library, so these modules depend on it.</p> + +<p><code>compile 'com.android.support:appcompat-v7:19.0.1'</code> declares a dependency on +version 19.0.1 of the Android Support Library by specifying its Maven coordinates. The Android Support +Library is available in the <em>Android Repository</em> package of the Android SDK. If your +SDK installation does not have this package, download and install it using the SDK Manager.</p> + +Android Studio configures projects to use the Maven Central Repository by default. (This +configuration is included in the top-level build file for the project.)</p> + +<h4>Local binary dependencies</h4> + +<p>Some modules do not use any binary dependencies from the +local file system. If you have modules that require local binary dependencies, copy the JAR +files for these dependencies into <code><moduleName>/libs</code> inside your project.</p> + +<p><code>compile fileTree(dir: 'libs', include: ['*.jar'])</code> tells the build system that any +JAR file inside <code>app/libs</code> is a dependency and should be included in the compilation +classpath and in the final package.</p> + +<p>For more information about dependencies in Gradle, see +<a href="http://www.gradle.org/docs/current/userguide/artifact_dependencies_tutorial.html">Dependency +Management Basics</a> in the Gradle User Guide.</p> + +<h3 id="runProguard">Run ProGuard</h3> + +<p>The build system can run +<a href="http://developer.android.com/tools/help/proguard.html">ProGuard</a> to obfuscate your +classes during the build process. In <code>BuildSystemExample</code>, modify the build file for +the app module to run ProGuard for the release build:</p> + +<pre> +... +android { + ... + buildTypes { + release { + minifyEnabled true + proguardFiles getDefaultProguardFile('proguard-android.txt'), \ + 'proguard-rules.txt' + } + } +} +... +</pre> + +<p><code>getDefaultProguardFile('proguard-android.txt')</code> obtains the default ProGuard +settings from the Android SDK installation. Android Studio adds the module-specific rules file +<code>proguard-rules.txt</code> at the root of the module, where you can add custom ProGuard +rules.</p> + +<h3 id="configureSigning">Configure signing settings</h3> + +<p>The debug and the release versions of the app differ on whether the application can be +debugged on secure devices and on how the APK is signed. The build system signs the debug +version with a default key and certificate using known credentials to avoid a password prompt at +build time. The build system does not sign the release version unless you explicitly define a +signing configuration for this build. If you do not have a release key, you can generate one as +described in <a href="{@docRoot}tools/publishing/app-signing.html">Signing your Applications</a>.</p> + + +<h2 id="workBuildVariants">Work with build variants</h2> + +<p>This section describes how the build system can help you create different versions of the same +application from a single project. This is useful when you have a demo version and a paid version +of your app, or if you want to distribute multiple APKs for different device configurations on +Google Play.</p> + +<p>The build system uses <em>product flavors</em> to create different product versions of your app. +Each product version of your app can have different features or device requirements. The build +system also uses build types to apply different build and packaging settings to each product version. +Each product flavor and build type combination forms a build variant. The build system generates a +different APK for each build variant of your app. </p> + +<h3>Build variants</h3> + +<p>This example project consists of the two default build types (<em>debug</em> and <em>release</em>) +and two product flavors for app type (demo and full). For more information on advanced uses of +build variants, see +<a href="{@docRoot}sdk/installing/studio-build.html"> Build System Overview</a> .</p> + + +<h4>Product flavors </h4> + +<p>To create different product versions of your app:</p> + +<ol> + <li>Define product flavors in the build file.</li> + <li>Create additional source directories for each flavor.</li> + <li>Add the flavor-specific sources to your project.</li> +</ol> + +<p>The rest of this section walks you through these steps in detail using a +<code>BuildSystemExample</code> project. You create two flavors of the +<code>BuildSystemExample</code> app, a demo flavor and a full flavor. Both flavors share +<code>MainActivity</code>, to which you add a new button to launch a new activity, +<code>SecondActivity</code>. This new activity is different for each flavor, so you simulate a +situation where the new activity would have more features in the full flavor than in the demo +flavor. At the end of the exercise, you end up with two different APKs, one for each flavor.</p> + +<h3>Define product flavors in the build file</h3> + +<p>To define two product flavors, edit the build file for the app module to add the following +configuration:</p> + +<pre> +... +android { + ... + defaultConfig { ... } + signingConfigs { ... } + buildTypes { ... } + productFlavors { + demo { + applicationId "com.buildsystemexample.app.demo" + versionName "1.0-demo" + } + full { + applicationId "com.buildsystemexample.app.full" + versionName "1.0-full" + } + } +} +... +</pre> + +<p>The product flavor definitions support the same properties as the <code>defaultConfig</code> +element. The base configuration for all flavors is specified in <code>defaultConfig</code>, and each +flavor overrides any default values. The build file above uses the <code>applicationId</code> +property to assign a different package name to each flavor: since each flavor definition creates a +different app, they each need a distinct package name.</p> + +<p class="note"><strong>Note:</strong> To distribute your app using +<a href="{@docRoot}google/play/publishing/multiple-apks.html">Multiple APK Support</a> in +Google Play, assign the same package name to all variants and give each variant a different +<code>versionCode</code>. To distribute different variants of your app as separate apps in Google +Play, assign a different package name to each variant.</p> + +<h4>Add additional source directories for each flavor</h4> + +<p>Now you create source folders and add a <code>SecondActivity</code> to each flavor. To create +the source directory structure for the demo flavor:</p> + +<ol> + <li>On the <em>Project</em> panel, expand <strong>BuildSystemExample</strong>, and then expand + the <strong>app</strong> directory.</li> + <li>Right-click the <strong>src</strong> directory under <em>app</em> and select + <strong>New</strong> > <strong>Directory</strong>.</li> + <li>Enter "demo" as the name of the new directory and click <strong>OK</strong>.</li> + <li><p>Similarly, create the following directories:</p> + <ul> + <li><code>app/src/demo/java</code></li> + <li><code>app/src/demo/res</code></li> + <li><code>app/src/demo/res/layout</code></li> + <li><code>app/src/demo/res/values</code></li> + </ul> + </li> +</ol> + +<p>The resulting directory structure looks like figure 1.</p> + +<img src="{@docRoot}images/tools/as-demoflavordirs.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> New source directories for the demo flavor.</p> + +<h4>Add a new activity to each flavor</h4> + +<p>To add <code>SecondActivity</code> to the <code>demo</code> flavor:</p> + +<ol> + <li>On the <em>Project</em> panel, right click on the <strong>app</strong> module and select + <strong>New</strong> > <strong>Activity</strong>.</li> + <li>Select <strong>Blank Activity</strong> and click <strong>Next</strong>.</li> + <li>Enter "SecondActivity" as the activity name.</li> + <li>Enter "com.buildsystemexample.app" as the package name and click + <strong>Finish</strong>.</li> + <li>Right click on the <strong>java</strong> directory under <em>app/src/demo</em> and select + <strong>New</strong> > <strong>Package</strong>.</li> + <li>Enter "com.buildsystemexample.app" as the package name and click <strong>OK</strong>.</li> + <li>Drag <strong>SecondActivity</strong> and drop it under the new package in + <em>app/src/demo/java</em>.</li> + <li>Accept the default values and click <strong>Refactor</strong>.</li> +</ol> + +<p>To add the layout for <code>SecondActivity</code> and a strings resource to the demo flavor:</p> + +<ol> + <li>Drag <strong>activity_second.xml</strong> from <em>app/src/main/res/layout</em> and drop it + inside <em>app/src/demo/res/layout</em>.</li> + <li>Accept the default values on the window that appears and click <code>OK</code>.</li> + <li>Copy <strong>strings.xml</strong> from <em>app/src/main/res</em> into + <em>app/src/demo/res</em>.</li> + <li><p>Replace the contents of the new copy of <code>strings.xml</code> with the + following:</p> + <p><pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="hello_world">Demo version only.</string> +</resources> +</pre></p> + </li> +</ol> + +<p>Now you add source folders and <code>SecondActivity</code> to the full flavor by making a copy +of the <code>demo</code> flavor:</p> + +<ol> + <li>On the <em>Project</em> panel, right click on the <strong>demo</strong> directory under + <em>app/src</em> and select <strong>Copy</strong>.</li> + <li>Right-click on the <strong>src/</strong> directory under <em>app/</em> and select + <strong>Paste</strong>.</li> + <li>On the window that appears, enter "full" as the new name and click <strong>OK</strong>.</li> + <li><p>Replace the contents of <strong>strings.xml</strong> under <em>src/full/res/values</em> + with the following:</p> + <p><pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="hello_world">This is the full version!</string> +</resources> +</pre></p> + </li> +</ol> + +<p class="note"><strong>Note:</strong> From this point on, you could develop +<code>SecondActivity</code> independently inside each +flavor. For example, you could add more features to this activity in the <code>full</code> flavor.</p> + +<p>To work on files from a particular flavor, click on <strong>Build Variants</strong> on the left +of the IDE window and select the flavor you want to modify in the <em>Build Variants</em> panel, +as shown in figure 2. Android Studio may show errors in source files from flavors other than the +one selected in the <em>Build Variants</em> panel, but this does not affect the outcome of the +build.</p> + +<img src="{@docRoot}images/tools/as-buildvariants.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> The Build Variants panel.</p> + +<h4>Launch a flavor-specific activity from the main activity</h4> + +<p>Since the flavor-specific activity (<code>SecondActivity</code>) has the same package name and +activity name in both flavors, you can launch it from the main activity, which is common to all +flavors. To modify the main activity:</p> + +<ol> + <li><p>Edit <code>activity_main.xml</code> and add a new button to + <code>MainActivity</code>:</p> + <p><pre> +<LinearLayout ...> + ... + <Button + android:id="@+id/button2" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button2" + android:onClick="onButton2Clicked"/> +</LinearLayout> +</pre></p> + </li> + <li>Click on the areas marked in red in the layout file and press <strong>Alt</strong>+ + <strong>Enter</strong>. Follow the suggestions from Android Studio to add a new string + resource with value “Open Second Activity” and an <code>onButton2Clicked</code> method to + <code>MainActivity</code>.</li> + <li><p>Add the following code to the <code>onButton2Clicked</code> method of + <code>MainActivity</code>:</p> + <p><pre> +public void onButton2Clicked(View view) { + Intent intent = new Intent(this, SecondActivity.class); + startActivity(intent); +} +</pre></p> + </li> + <li><p>Edit the app's manifest to include a reference to <code>SecondActivity</code>:</p> + <p><pre> +<manifest ...> + <application ...> + ... + <activity + android:name="com.buildsystemexample.app.SecondActivity" + android:label="@string/title_activity_second" > + </activity> + </application> +</manifest> +</pre></p> + </li> +</ol> + + +<h4>Build types </h4> +<p>Build types represent the build packaging versions generated for each app package. By default, +the debug and release build types are provided. +</p> + +<pre> +... +android { + ... + defaultConfig { ... } + signingConfigs { ... } + buildTypes { ... } + productFlavors {...} + buildTypes { + release { + minifyEnabled false + proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' + } + debug { + debuggable true + } + } +} +... +</pre> + +<p class="note"><strong>Note:</strong> Although only the <em>release</em> build type appears in +the default <strong>build.gradle</strong> file, both the release and debug build types are +applied to each build. </p> + +<p>In this example, the product flavors and build types create the following build variants: +<ul> +<li>demoDebug</li> +<li>demoRelease</li> +<li>fullDebug</li> +<li>fullRelease</li> +</ul> + +<p>To build this example, invoke the <code>assemble</code> task from Android Studio or from the +command line.</p> + +<p>Separate output folders are created for each build variant. </p> |