am 6cc5e87d: am 4083327e: docs:build system updates [CP]
* commit '6cc5e87d65b88d63082640b8e506d75f3d9244de':
docs:build system updates [CP]
diff --git a/docs/html/images/tools/buildfilebasics_appbuildfile.png b/docs/html/images/tools/buildfilebasics_appbuildfile.png
new file mode 100644
index 0000000..ff5a184
--- /dev/null
+++ b/docs/html/images/tools/buildfilebasics_appbuildfile.png
Binary files differ
diff --git a/docs/html/images/tools/studio-gradle-tab.png b/docs/html/images/tools/studio-gradle-tab.png
new file mode 100644
index 0000000..b0f302c
--- /dev/null
+++ b/docs/html/images/tools/studio-gradle-tab.png
Binary files differ
diff --git a/docs/html/images/tools/studio-main-screen.png b/docs/html/images/tools/studio-main-screen.png
new file mode 100644
index 0000000..e898d2f
--- /dev/null
+++ b/docs/html/images/tools/studio-main-screen.png
Binary files differ
diff --git a/docs/html/images/tools/studio-module-build-file.png b/docs/html/images/tools/studio-module-build-file.png
new file mode 100644
index 0000000..c02f00a
--- /dev/null
+++ b/docs/html/images/tools/studio-module-build-file.png
Binary files differ
diff --git a/docs/html/images/tools/studio-project-build-file.png b/docs/html/images/tools/studio-project-build-file.png
new file mode 100644
index 0000000..3ee38bf
--- /dev/null
+++ b/docs/html/images/tools/studio-project-build-file.png
Binary files differ
diff --git a/docs/html/sdk/installing/studio-build.jd b/docs/html/sdk/installing/studio-build.jd
index bff3bc0..c80368f 100644
--- a/docs/html/sdk/installing/studio-build.jd
+++ b/docs/html/sdk/installing/studio-build.jd
@@ -1,4 +1,4 @@
-page.title=Building Your Project with Gradle
+page.title=Build System Overview
@jd:body
@@ -6,1066 +6,100 @@
<div id="qv">
<h2>In this document</h2>
<ol>
- <li><a href="#overviewBuild">Overview of the Build System</a>
- <ol>
- <li><a href="#buildConf">Build configuration</a></li>
- <li><a href="#buildConv">Build by convention</a></li>
- <li><a href="#projectModules">Projects and modules</a></li>
- <li><a href="#dependencies">Dependencies</a></li>
- <li><a href="#buildTasks">Build tasks</a></li>
- <li><a href="#gradleWrapper">The Gradle wrapper</a></li>
- </ol>
- </li>
- <li><a href="#creatingBuilding">Create and Build a Project</a>
- <ol>
- <li><a href="#createProject">Create a project</a></li>
- <li><a href="#projectStructure">Project structure</a></li>
- <li><a href="#addLibModule">Add a library module</a></li>
- <li><a href="#buildProject">Build the project</a></li>
- <li><a href="#buildCmd">Build from the command line</a></li>
- <li><a href="#buildRelease">Build a release version</a></li>
- </ol>
- </li>
- <li><a href="#configBuild">Configure the Build</a>
- <ol>
- <li><a href="#buildFileBasics">Build file basics</a></li>
- <li><a href="#declareDeps">Declare dependencies</a></li>
- <li><a href="#runProguard">Run ProGuard</a></li>
- <li><a href="#configureSigning">Configure signing settings</a></li>
- <li><a href="#workBuildVariants">Work with build variants</a></li>
- </ol>
- </li>
- <li><a href="#reference">Reference</a></li>
+ <li><a href="#detailed-build">A Detailed Look at the Build Process</a> </li>
</ol>
<h2>See also</h2>
<ul>
-<li><a href="{@docRoot}sdk/installing/studio.html">
-Getting Started with Android Studio</a></li>
-<li><a href="{@docRoot}sdk/installing/studio-tips.html">
-Android Studio Tips and Tricks</a></li>
-<li><a href="{@docRoot}sdk/installing/migrate.html">
-Migrating from Eclipse</a></li>
+ <li><a href="{@docRoot}sdk/installing/studio.html">
+ Getting Started with Android Studio</a></li>
+ <li><a href="{@docRoot}tools/studio/index.html">Android Studio Basics</a></li>
+ <li><a href="{@docRoot}tools/eclipse/migrate-adt.html">Migrating from Eclipse</a></li>
</div>
</div>
-<a class="notice-developers-video"
-href="https://developers.google.com/events/io/sessions/324603352">
+<a class="notice-developers-video" href="https://www.youtube.com/watch?v=LCJAgPkpmR0#t=504">
<div>
<h3>Video</h3>
- <p>What's New in Android Developer Tools</p>
+ <p>The New Android SDK Build System</p>
</div>
</a>
-<p>The Android Studio build system is the toolkit you use to build, test, run and package
-your apps. The build system is independent from Android Studio, so you can invoke it from Android
-Studio or from the command line. After you write your application, you can use the features
-of the build system to:</p>
+<p>The Android build system is the toolkit you use to build, test, run and package
+your apps. The build system can run as an integrated tool from the Android Studio menu and
+independently from the command line. You can use the features of the build system to:</p>
<ul>
<li>Customize, configure, and extend the build process.</li>
- <li>Create multiple APKs for your app with different features using the same project.</li>
- <li>Reuse code and resources.</li>
+ <li>Create multiple APKs for your app with different features using the same project and
+ modules.</li>
+ <li>Reuse code and resources across source sets.</li>
</ul>
-<p>The flexibility of the Android Studio build system enables you to achieve all of this without
-modifying your app's core project files.</p>
+<p>The flexibility of the Android build system enables you to achieve all of this without
+modifying your app's core source files. To build an Android Studio project, see
+<a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android Studio</a>.
+To configure custom build settings in an Android Studio project, see
+<a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>.</p>
-<h2 id="overviewBuild">Overview of the Build System</h2>
+<h2 id="detailed-build">A Detailed Look at the Build Process</h2>
-<p>The Android Studio build system consists of an Android plugin for <em>Gradle</em>.
-<a href="http://www.gradle.org/">Gradle</a> is an advanced build toolkit that manages dependencies
-and allows you to define custom build logic. Many software projects use Gradle to manage their
-builds. The Android plugin for Gradle does not depend on Android Studio, although Android Studio
-is fully integrated with it. This means that:</p>
+<p>The build process involves many tools and processes that generate intermediate files on the
+way to producing an <code>.apk</code>. If you are developing in Android Studio, the complete build
+process is done every time you run the Gradle build task for your project or modules. The build
+process is very flexible so it's useful, however, to understand what is happening under the hood
+since much of the build process is configurable and extensible. The following diagram depicts the
+different tools and processes that are involved in a build:</p>
-<ul>
- <li>You can build your Android apps from the command line on your machine or on machines
- where Android Studio is not installed (such as continuous integration servers).</li>
- <li>You can build your Android apps from Android Studio with the same custom build
- configuration and logic as when you build from the command line.</li>
-</ul>
+ <img src="{@docRoot}images/build.png" />
-<p>The output of the build is the same whether you are building a project from the command line,
-on a remote machine, or using Android Studio.</p>
+<p>The general process for a typical build is outlined below. The build system merges all the
+resources from the configured product flavors, build types, and dependencies. If different
+folders contain resources with the same name or setting, the following override priority order is:
+dependencies override build types, which override product flavors, which override the main source
+directory.</p>
-<h3 id="buildConf">Build configuration</h3>
+ <ul>
-<p>The build configuration for your project is defined inside <em>Gradle build files</em>,
-which are plain text files that use the syntax and options from Gradle and the Android plugin
-to configure the following aspects of your build:</p>
+ <li>The Android Asset Packaging Tool (aapt) takes your application resource files, such as the
+ <code>AndroidManifest.xml</code> file and the XML files for your Activities, and compiles them.
+ An <code>R.java</code> is also produced so you can reference your resources from your Java code.</li>
-<ul>
- <li><em>Build variants</em>. The build system can generate multiple APKs with different
- configurations for the same project. This is useful when you want to build different
- versions of your application without having to create a separate project for each of
- them.</li>
- <li><em>Dependencies</em>. The build system manages project dependencies and supports
- dependencies from your local filesystem and from remote repositories. This prevents you
- from having to search, download, and copy binary packages for your dependencies into your
- project directory.</li>
- <li><em>Manifest entries</em>. The build system enables you to specify values for some
- elements of the manifest file in the build configuration. These new values override the
- existing values in the manifest file. This is useful if you want to generate multiple APKs
- for your project where each of them has a different package name, minimum SDK version, or
- target SDK version.</li>
- <li><em>Signing</em>. The build system enables you to specify signing settings in the build
- configuration, and it can sign your APKs during the build process.</li>
- <li><em>ProGuard</em>. The build system enables you to specify a different
- <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> rules
- file for each build variant. The build system can run ProGuard to obfuscate your classes
- during the build process.</li>
- <li><em>Testing</em>. The build system generates a test APK from the test sources in your
- project, so you do not have to create a separate test project. The build system can run
- your tests during the build process.</li>
-</ul>
+ <li>The aidl tool converts any <code>.aidl</code> interfaces that you have into Java interfaces.</li>
-<p>Gradle build files use <em>Groovy</em> syntax.
-<a href="http://groovy.codehaus.org/">Groovy</a> is a dynamic language that you can use to
-define custom build logic and to interact with the Android-specific elements provided by the
-Android plugin for Gradle.</p>
+ <li>All of your Java code, including the <code>R.java</code> and <code>.aidl</code> files, are
+ compiled by the Java compiler and .class files are output.</li>
-<h3 id="buildConv">Build by convention</h3>
+ <li>The dex tool converts the .class files to Dalvik byte code. Any 3rd party libraries and
+ .class files that you have included in your module build are also converted into <code>.dex</code>
+ files so that they can be packaged into the final <code>.apk</code> file.</li>
-<p>The Android Studio build system assumes <em>sensible defaults</em> for the project structure
-and other build options. If your project adheres to these conventions, your Gradle build files are
-very simple. When some these conventions do not apply to your project, the flexibility of the
-build system allows you to configure almost every aspect of the build process. For example, if
-the sources for your project are located in a different directory than the default, you can
-specify this location in the build file.</p>
+ <li>All non-compiled resources (such as images), compiled resources, and the .dex files are
+ sent to the apkbuilder tool to be packaged into an <code>.apk</code> file.</li>
-<h3 id="projectModules">Projects and modules</h3>
+ <li>Once the <code>.apk</code> is built, it must be signed with either a debug or release key
+ before it can be installed to a device.</li>
-<p>A <em>project</em> in Android Studio represents a complete Android app. Android Studio
-projects consist of one or more modules. A <em>module</em> is a component of your app that you can
-build, test, or debug independently. Modules contain the source code and resources for your app.
-Android Studio projects contain three kinds of modules:</p>
+ <li>Finally, if the application is being signed in release mode, you must align the
+ <code>.apk</code> with the zipalign tool. Aligning the final <code>.apk</code> decreases memory
+ usage when the application is -running on a device.</li>
+ </ul>
-<ul>
- <li><em>Java library modules</em> contain reusable code. The build system generates a
- JAR package for Java library modules.</li>
- <li><em>Android library modules</em> contain reusable Android-specific code and resources.
- The build system generates an AAR (Android ARchive) package for library modules.</li>
- <li><em>Android application modules</em> contain application code and may depend on library
- modules, although many Android apps consists of only one application module. The build
- system generates an APK package for application modules.</li>
-</ul>
+<p class="note"><b>Note:</b> Apps are limited to a 64K method reference limit. If your app reaches
+this limit, the build process outputs the following error message:
-<p>Android Studio projects contain a top-level Gradle build file that lists all the modules in
-the project, and each module contains its own Gradle build file.</p>
+<pre>Unable to execute dex: method ID not in [0, 0xffff]: 65536.</pre>
-<h3 id="dependencies">Dependencies</h3>
+To avoid this error, see
+<a href="{@docRoot}tools/building/multidex.html">Building Apps with Over 65K Methods</a>.
+</p>
-<p>The Android Studio build system manages project dependencies and supports module dependencies,
-local binary dependencies, and remote binary dependencies.</p>
-<dl>
- <dt><em>Module Dependencies</em></dt>
- <dd><p>A project module can include in its build file a list of other modules it depends on.
- When you build this module, the build system assembles and includes the required
- modules.</p></dd>
- <dt><em>Local Dependencies</em></dt>
- <dd><p>If you have binary archives in your local filesystem that a module depends on, such as
- JAR files, you can declare these dependencies in the build file for that
- module.</p></dd>
- <dt><em>Remote Dependencies</em></dt>
- <dd><p>When some of your dependencies are available in a remote repository, you do not have
- to download them and copy them into your project. The Android Studio build system supports
- remote <em>Maven</em> dependencies. <a href="http://maven.apache.org/">Maven</a> is a
- popular software project management tool that helps organize project dependencies using
- repositories.</p>
- <p>Many popular software libraries and tools are available in public Maven repositories.
- For these dependencies you only have to specify their Maven coordinates, which uniquely
- identify each element in a remote repository. The format for Maven coordinates used in the
- build system is <code>group:name:version</code>. For example, the Maven coordinates for
- version 16.0.1 of the Google Guava libraries are
- <code>com.google.guava:guava:16.0.1</code>.</p>
- <p>The <a href="http://search.maven.org">Maven Central Repository</a> is widely used to
- distribute many libraries and tools.</p>
- </dd>
-</dl>
+<h3>Build output</h3>
-<h3 id="buildTasks">Build tasks</h3>
-
-<p>The Android Studio build system defines a hierarchical set of build tasks: the top-level
-tasks invoke the tasks they depend on to produce the necessary outcomes. The build system
-provides project tasks to build your app and module tasks to build modules independently.</p>
-
-<p>You can view the list of available tasks and invoke any task from Android Studio and from
-the command line, as described in
-<a href="#buildProject">Build the project in Android Studio</a> and and
-<a href="#buildCmd">Build the project from the command line</a>.</p>
-
-<h3 id="gradleWrapper">The Gradle wrapper</h3>
-
-<p>Android Studio projects contain the <em>Gradle wrapper</em>, which consists of:</p>
-
-<ul>
- <li>A JAR file</li>
- <li>A properties file</li>
- <li>A shell script for Windows platforms</li>
- <li>A shell script for Mac and Linux platforms</li>
-</ul>
-
-<p class="note"><strong>Note:</strong> You should submit all of these files to your source
-control system.</p>
-
-<p>Using the Gradle wrapper (instead of the local Gradle installation) ensures that
-you always run the version of Gradle defined in the properties file. To configure your project
-to use a newer version of Gradle, edit the properties file and specify the new version there.
-
-<p>Android Studio reads the properties file from the Gradle wrapper directory inside your project
-and runs the wrapper from this directory, so you can seamlessly work with multiple projects
-that require different versions of Gradle.</p>
-
-<p class="note"><strong>Note:</strong> Android Studio does not use the shell scripts, so any
-changes you make to them won't work when building from the IDE. You should define your custom
-logic inside Gradle build files instead.</p>
-
-<p>You can run the shell scripts to build your project from the command line on your development
-machine and on other machines where Android Studio is not installed.</p>
-
-
-<h2 id="creatingBuilding">Create and Build an Android Studio Project</h2>
-
-<p>This section builds on the concepts presented above and shows you how to:</p>
-
-<ul>
- <li>Create projects and modules.</li>
- <li>Work with the project structure.</li>
- <li>Edit build files to configure the build process.</li>
- <li>Build and run your app.</li>
-</ul>
-
-<h3 id="createProject">Create a project in Android Studio</h3>
-
-<p>To create a new project in Android Studio:</p>
-
-<ol>
- <li>Click <strong>File</strong> and select <strong>New Project</strong>.</li>
- <li>In the window that appears, enter "BuildSystemExample" in the <em>Application</em>
- name field.</li>
- <li>Leave the rest of the values unchanged and click <strong>Next</strong>.</li>
- <li>Leave the default icon settings unchanged and click <strong>Next</strong>.</li>
- <li>Select <em>Blank Activity</em> and click <strong>Next</strong>.</li>
- <li>Leave the default activity and layout names unchanged and click
- <strong>Finish</strong>.</li>
-</ol>
-
-<p>Figure 1 shows how the Android Studio window looks like after creating the project.</p>
-
-<img src="{@docRoot}images/tools/as-mainscreen.png" alt="" />
-<p class="img-caption"><strong>Figure 1.</strong> Previewing your app.</p>
-
-<h3 id="projectStructure">The project structure</h3>
-
-<p>Android Studio projects contain an application module by default (<code>app</code>).
-Table 1 lists where the main components of your app are located inside this module.</p>
-
-<p class="table-caption" id="table1">
-<strong>Table 1.</strong> Default location of the components in an application module.</p>
-<table>
- <tr>
- <th scope="col">Component</th>
- <th scope="col">Location</th>
- </tr>
- <tr>
- <td>Source files</td>
- <td><code>app/src/main/java/<package>/</code></td>
- </tr>
- <tr>
- <td>Resource files</td>
- <td><code>app/src/main/res/</code></td>
- </tr>
- <tr>
- <td>Manifest file</td>
- <td><code>app/src/main/AndroidManifest.xml</code></td>
- </tr>
- <tr>
- <td>Build file</td>
- <td><code>app/build.gradle</code></td>
- </tr>
-</table>
-
-<p>When you add additional modules to your project, the directory structure for each module is
-similar to the one shown in table 1, replacing <code>app</code> by the name of the module.</p>
-
-<h3 id="addLibModule">Add a library module</h3>
-
-<p>This section shows you how to add a library module to your project and how to add this
-library as a dependency of an application module.</p>
-
-<h4>Create a new library module</h4>
-
-<p>It is good development practice to group functionality that you may reuse in other apps inside
-a library module. To create a library module inside the <code>BuildSystemExample</code>
-project:</p>
-
-<ol>
- <li>Click <strong>File</strong> and select <strong>New Module</strong>.</li>
- <li>On the window that appears, select <strong>Android Library</strong> and click
- <strong>Next</strong>.</li>
- <li>Leave the default module name (<code>lib</code>) unchanged and click
- <strong>Next</strong>.</li>
- <li>Select <em>Blank Activity</em> and click <strong>Next</strong>.</li>
- <li>Type "LibActivity1" on the <em>Activity Name</em> field and click
- <strong>Finish</strong>.</li>
-</ol>
-
-<p>The project now contains two modules, <code>app</code> and <code>lib</code>, with one activity
-in each module.</p>
-
-<h4 id="openActFromLib">Open an activity from a library module</h4>
-
-<p>Library modules contain activities and other logic that one or more application modules reuse.
-In this example, <code>MainActivity</code> in the app module opens <code>LibActivity1</code>
-from the <code>lib</code> module. To open <code>LibActivity1</code> from
-<code>MainActivity</code>:</p>
-
-<ol>
- <li>
- <p>Edit the layout file for <code>MainActivity</code> in the <code>app</code> module.
- This file is located in <code>app/src/main/res/layout/activity_main.xml</code>. Replace
- the contents of this file with the following:</p>
- <p><pre>
-<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
- xmlns:tools="http://schemas.android.com/tools"
- android:layout_width="match_parent"
- android:layout_height="match_parent"
- tools:context="com.buildsystemexample.app.MainActivity">
-
- <Button
- android:id="@+id/button1"
- android:layout_width="wrap_content"
- android:layout_height="wrap_content"
- android:text="@string/button1"
- android:onClick="onButton1Clicked"/>
-
-</LinearLayout>
-</pre></p>
- </li>
- <li>
- In this layout file, click on the line that contains
- <code>android:text="@string/button1"</code> and press <strong>Alt+Enter</strong>. Follow
- the suggestion from Android Studio to add a string resource with the value
- "Open LibActivity1".
- </li>
- <li>
- In this layout file, click on the line that contains
- <code>android:onClick="onButton1Clicked"</code> and press <strong>Alt+Enter</strong>.
- Follow the suggestion from Android Studio to add the <code>onButton1Clicked</code>
- method to <code>MainActivity</code>.
- </li>
- <li>
- <p>Copy the following code inside the <code>onButton1Clicked</code> method in
- <code>MainActivity</code>:</p>
- <p><pre>
-public void onButton1Clicked(View view) {
- Intent intent = new Intent(this, LibActivity1.class);
- startActivity(intent);
-}</pre></p>
- </li>
- <li>
- Click on <code>LibActivity1</code> in the first line inside the
- <code>onButton1Clicked</code> method of <code>MainActivity</code> and press
- <strong>Alt+Enter</strong>. Follow the suggestion from Android Studio to add an import
- for <code>LibActivity1</code> from the lib module.
- </li>
-</ol>
-
-<p>When the user taps the <strong>Open LibActivity1</strong> button on <code>MainActivity</code>
-(from the <code>app</code> module), <code>LibActivity1</code> (from the <code>lib</code> module)
-starts.</p>
-
-<h4>Add a dependency on a library module</h4>
-
-<p>The <code>app</code> module now depends on the <code>lib</code> module, but the build system
-does not know about this yet. Edit the build file for the <code>app</code> module (
-<code>app/build.gradle</code>) and add a dependency on the <code>lib</code> module:</p>
-
-<pre>
-...
-dependencies {
- ...
- compile project(":lib")
-}
-</pre>
-
-<p>The <code>lib</code> module can still be built and tested independently, and the build system
-creates an AAR package for it that you could reuse in other projects.</p>
-
-<h3 id="buildProject">Build the project in Android Studio</h3>
-
-<p>To build the project on Android Studio, click <strong>Build</strong> and select
-<strong>Make Project</strong>. The status bar at the bottom of the window shows the current
-progress of the build:</p>
-
-<p><code>Gradle: Executing tasks: [:app:assembleDebug, :lib:bundleDebug]</code></p>
-
-<p class="note">If your project uses product flavors, Android Studio invokes the task for the
-selected build variant. For more information, see <a href="#workBuildVariants">Work with build
-variants.</a></p>
-
-<p>Click <img src="{@docRoot}images/tools/as-gradlebutton.png" alt=""
-style="vertical-align:bottom;margin:0;"/> on the bottom
-right part of the window to show the <em>Gradle Console</em>, as shown in figure 2.</p>
-
-<img src="{@docRoot}images/tools/as-gradleconsole.png" alt="" />
-<p class="img-caption"><strong>Figure 2.</strong> The Gradle Console in Android Studio.</p>
-
-<p>The Gradle Console shows the build tasks and subtasks that the build system runs for
-Android Studio. If the build fails, you can find more details on the console. To hide the Gradle
-Console, click <img src="{@docRoot}images/tools/as-gradlebutton.png" alt=""
-style="vertical-align:bottom;margin:0;"/> again.</p>
-
-<p>To view the list of all available build tasks in Android Studio, click <strong>Gradle</strong>
-on the right side of the IDE window. The <em>Gradle tasks</em> panel appears as shown in
-figure 3. Double-click any build task to run it in Android Studio. To hide the <em>Gradle tasks</em>
-panel, click <strong>Gradle</strong> again.</p>
-
-<img src="{@docRoot}images/tools/as-gradlepanel.png" alt="" />
-<p class="img-caption"><strong>Figure 3.</strong> The list of build tasks in Android Studio.</p>
-
-
-<h3 id="buildCmd">Build the project from the command line</h3>
-
-<p>To build the project from the command line, open a terminal window and navigate to the project
-root. On Windows platforms, type this command:</p>
-
-<pre>
-> gradlew.bat assembleDebug
-</pre>
-
-<p>On Mac OS and Linux platforms, type these commands:</p>
-
-<pre>
-$ chmod +x gradlew
-$ ./gradlew assembleDebug
-</pre>
-
-<p>The first command (<code>chmod</code>) adds the execution permission to the Gradle wrapper
-script and is only necessary the first time you build this project from the command line.</p>
-
-<p>The output of <code>gradlew</code> is similar to the output in the Gradle Console from
-figure 2.</p>
-
-<p>The <code>assembleDebug</code> build task builds the debug version of your app and signs it
-with the default local certificate, so that you can install it on the emulator and on real devices
-for debugging purposes.</p>
-
-<p>After you build the project, the output APK for the app module is located in
-<code>app/build/outputs/apk/</code>, and the output AAR for the lib module is located in
-<code>lib/build/outputs/libs/</code>.</p>
-
-<p>To see a list of all available build tasks for your project, type this command:</p>
-
-<pre>
-$ ./gradlew tasks
-</pre>
-
-
-<h3 id="buildRelease">Build a release version</h3>
-
-<p>You can build the release version of your application from the command line or using Android
-Studio. To build it from the command line, invoke the <code>assembleRelease</code> build task using
-the Gradle wrapper script (<code>gradlew assembleRelease</code>). To build it from Android
-Studio:</p>
-
-<ol>
- <li>Click <strong>Gradle</strong> on the right side of the IDE window.</li>
- <li>On the <em>All tasks</em> section of the sidebar that appears, expand
- <strong>BuildSystemExample</strong>.</li>
- <li>Expand <strong>:app</strong> and double-click <strong>assembleRelease</strong>.</li>
-</ol>
-
-<p>You can use this procedure to invoke any build task from Android Studio.</p>
-
-
-
-<h2 id="configBuild">Configure the Build</h2>
-
-<p>This section uses the <code>BuildSystemExample</code> project from the previous section and
-shows you how to:</p>
-
-<ul>
- <li>Use the syntax from the Android plugin for Gradle in build files.</li>
- <li>Declare dependencies.</li>
- <li>Configure ProGuard settings.</li>
- <li>Configure signing settings.</li>
- <li>Work with build variants.</li>
-</ul>
-
-<h3 id="buildFileBasics">Build file basics</h3>
-
-<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 {
- runProguard 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 4.</strong> Sync the project in Android Studio.</p>
-
-<h3 id="declareDeps">Declare dependencies</h3>
-
-<p>The <code>app</code> module in <code>BuildSystemExample</code> 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>The modules in <code>BuildSystemExample</code> 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 {
- runProguard 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.</p>
-
-<p>To sign the release version of <code>BuildSystemExample</code>:</p>
-
-<ol>
- <li><p>Copy your release key to the root directory of the <code>app</code> module
- (<code>app/</code>).</p>
- <p>This ensures that the build system can find your key when you move the location of your
- project or when you build the project on a different machine. 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>
- </li>
- <li><p>Add the signing configuration to the build file for the <code>app</code> module:</p>
- <p><pre>
-...
-android {
- ...
- defaultConfig { ... }
- signingConfigs {
- release {
- storeFile file("myreleasekey.keystore")
- storePassword "password"
- keyAlias "MyReleaseKey"
- keyPassword "password"
- }
- }
- buildTypes {
- release {
- ...
- signingConfig signingConfigs.release
- }
- }
-}
-...
-</pre></p>
- </li>
- <li>Invoke the <code>assembleRelease</code> build task from Android Studio or from the command
- line.</li>
-</ol>
-
-<p>The package in <code>app/build/apk/app-release.apk</code> is now signed with your release key.</p>
-
-<p class="note"><strong>Note:</strong> Including the passwords for your release key and keystore
-inside the build file is not a good security practice. Alternatively, you can configure the build
-file to obtain these passwords from environment variables or have the build process prompt you
-for these passwords.</p>
-
-<p>To obtain these passwords from environment variables:</p>
-
-<pre>
-storePassword System.getenv("KSTOREPWD")
-keyPassword System.getenv("KEYPWD")
-</pre>
-
-<p>To have the build process prompt you for these passwords if you are invoking the build from
-the command line:</p>
-
-<pre>
-storePassword System.console().readLine("\nKeystore password: ")
-keyPassword System.console().readLIne("\nKey password: ")
-</pre>
-
-<h3 id="workBuildVariants">Work with build variants</h3>
-
-<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 versions of your app. Each
-version of your app can have different features or device requirements. The build system generates
-a different APK for each version of your app.</p>
-
-<h4>Build variants</h4>
-
-<p>Each version of your app is represented in the build system by a <em>build variant</em>.
-Build variants are combinations of build types and product flavor configurations. Android Studio
-projects define two build types (<em>debug</em> and <em>release</em>) and no product flavors by
-default. These projects consists of two build variants, debug and release, and the build system
-generates an APK for each.</p>
-
-<p>The exercise in this section defines two product flavors, <em>demo</em> and <em>full</em>.
-This generates four build variants:</p>
-
-<ul>
- <li>demo-debug</li>
- <li>demo-release</li>
- <li>full-debug</li>
- <li>full-release</li>
-</ul>
-
-<p>In this case the build system creates four APKs, one for each of these build variants.</p>
-
-<p>Some projects have complex combinations of features along more than one dimension, but they
-still represent the same app. For example, in addition to having a demo and a full version of the
-app, some games may contain binaries specific to a particular CPU/ABI. The flexibility of
-the build system makes it possible to generate the following build variants for such a project:</p>
-
-<ul>
- <li>x86-demo-debug</li>
- <li>x86-demo-release</li>
- <li>x86-full-debug</li>
- <li>x86-full-release</li>
- <li>arm-demo-debug</li>
- <li>arm-demo-release</li>
- <li>arm-full-debug</li>
- <li>arm-full-release</li>
- <li>mips-demo-debug</li>
- <li>mips-demo-release</li>
- <li>mips-full-debug</li>
- <li>mips-full-release</li>
-</ul>
-
-<p>This project would consist of two build types (<em>debug</em> and <em>release</em>)
-and two <em>dimensions</em> of product flavors, one for app type (demo or full) and one for
-CPU/ABI (x86, ARM, or MIPS). For more information on flavor dimensions, see the
-<a href="http://tools.android.com/tech-docs/new-build-system/user-guide">Gradle Plugin User
-Guide</a>.</p>
-
-<h4>Source directories</h4>
-
-<p>To build each version of your app, the build system combines source code and
-resources from:</p>
-
-<ul>
- <li><code>src/main/</code> - the main source directory (common to all variants)</li>
- <li><code>src/<buildType>/</code> - the build type source directory</li>
- <li><code>src/<flavorName>/</code> - the flavor source directory</li>
-</ul>
-
-<p>The number of flavor source directories used in the build depends on the flavor configuration
-of your project:</p>
-<ul>
- <li><p>For projects that do not define any flavors, the build system does not use any
- flavor source directories. For example, to generate the <em>release</em> build variant
- in projects with no flavors, the build system uses:</p>
- <ul>
- <li><code>src/main/</code></li>
- <li><code>src/release/</code> (build type)</li>
- </ul>
- </li>
- <li><p>For projects that define a set of flavors, the build system uses one flavor source
- directory. For example, to generate the <em>full-debug</em> build variant in the example
- in this section, the build system uses:</p>
- <ul>
- <li><code>src/main/</code></li>
- <li><code>src/debug/</code> (build type)</li>
- <li><code>src/full/</code> (flavor)</li>
- </ul>
- </li>
- <li><p>For projects that use flavor dimensions, the build system uses one flavor source
- directory per dimension. For example, to generate the <em>arm-demo-release</em> build
- variant in the previous example, the build system uses:</p>
- <ul>
- <li><code>src/main/</code></li>
- <li><code>src/release/</code> (build type)</li>
- <li><code>src/demo/</code> (flavor - app type dimension)</li>
- <li><code>src/arm/</code> (flavor - ABI dimension)</li>
- </ul>
- </li>
-</ul>
-
-<p class="note"><strong>Note:</strong> The build type and flavor source directories are optional,
-and Android Studio does not create these directories for you. The build system does not use them
-if they are not present.</p>
-
-<p>The source code from these directories is used together to generate the output for a build
-variant. You can have classes with the same name in different directories as long as those
-directories are not used together in the same variant. The exercise in this section shows you
-how to create different versions of the same activity class in different variants.</p>
-
-<p>The build system merges all the manifests into a single manifest, so each build variant
-can define different components or permissions in the final manifest.</p>
-
-<p>The build system merges all the resources from the all the source directories. If different
-folders contain resources with the same name for a build variant, the priority order is the
-following: build type resources override those from the product flavor, which override the
-resources in the main source directory.</p>
-
-<p class="note"><strong>Note:</strong> Build variants enable you to reuse common activities,
-application logic, and resources across different versions of your app.</p>
-
-<h4>Product flavors in BuildSystemExample</h4>
-
-<p>To create different 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 the
-<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>
-
-<h4>Define product flavors in the build file</h4>
-
-<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 can override any value. 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 5.</p>
-
-<img src="{@docRoot}images/tools/as-demoflavordirs.png" alt="" />
-<p class="img-caption"><strong>Figure 5.</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. You can 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 5. 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 6.</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 output</h4>
-
-<p>The <code>BuildSystemExample</code> app is now complete. To build it, invoke the
-<code>assemble</code> task from Android Studio or from the command line.</p>
-
-<p>The build generates an APK for each build variant:
+<p>The build generates an APK for each build variant in the <code>app/build</code> folder:
the <code>app/build/apk/</code> directory contains packages named
<code>app-<flavor>-<buildtype>.apk</code>; for example, <code>app-full-release.apk</code> and
<code>app-demo-debug.apk</code>.</p>
-<h2 id="reference">Reference</h2>
-
-<p>The build system is very flexible and has more features than those described here. For a
-complete reference, see the
-<a href="http://tools.android.com/tech-docs/new-build-system/user-guide">Android Plugin for Gradle
-User Guide</a>.</p>
diff --git a/docs/html/tools/building/building-cmdline-ant.jd b/docs/html/tools/building/building-cmdline-ant.jd
new file mode 100644
index 0000000..51158de
--- /dev/null
+++ b/docs/html/tools/building/building-cmdline-ant.jd
@@ -0,0 +1,381 @@
+page.title=Building and Running from the Command Line
+parent.title=Building and Running
+parent.link=index.html
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#DebugMode">Building in Debug Mode</a></li>
+ <li><a href="#ReleaseMode">Building in Release Mode</a>
+ <ol>
+ <li><a href="#ManualReleaseMode">Build unsigned</a></li>
+ <li><a href="#AutoReleaseMode">Build signed and aligned</a></li>
+ <li><a href="#OnceBuilt">Once built and signed in release mode</a></li>
+ </ol>
+ </li>
+ <li><a href="#RunningOnEmulator">Running on the Emulator</a></li>
+ <li><a href="#RunningOnDevice">Running on a Device</a></li>
+ <li><a href="#Signing">Application Signing</a></li>
+ <li><a href="#AntReference">Ant Command Reference</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from
+the Command Line</a></li>
+ <li><a href="{@docRoot}tools/devices/emulator.html">Using the Android
+Emulator</a></li>
+ <li><a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>There are two ways to build your application using the Ant build script: one for
+ testing/debugging your application — <em>debug mode</em> — and one for building your
+ final package for release — <em>release mode</em>. Regardless of which way you build your application,
+ it must be signed before it can install on an emulator or device—with a debug key when building
+ in debug mode and with your own private key when building in release mode.</p>
+
+ <p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile
+ and build your project. This will create the .apk file that you can install on an emulator or device.
+ When you build in debug mode, the .apk file is automatically signed by the SDK tools with
+ a debug key, so it's instantly ready for installation onto an emulator or attached
+ development device. You cannot distribute an application that is signed with a debug key.
+ When you build in release mode, the .apk file is <em>unsigned</em>, so you
+ must manually sign it with your own private key, using Keytool and Jarsigner.</p>
+
+ <p>It's important that you read and understand <a href=
+ "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>, particularly once
+ you're ready to release your application and share it with end-users. That document describes the
+ procedure for generating a private key and then using it to sign your .apk file. If you're just
+ getting started, however, you can quickly run your applications on an emulator or your own
+ development device by building in debug mode.</p>
+
+ <p>If you don't have Ant, you can obtain it from the <a href="http://ant.apache.org/">Apache Ant
+ home page</a>. Install it and make sure it is in your executable PATH. Before calling Ant, you
+ need to declare the JAVA_HOME environment variable to specify the path to where the JDK is
+ installed.</p>
+
+ <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install
+ in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of
+ the space. To fix the problem, you can specify the JAVA_HOME variable like this:
+ <pre>set JAVA_HOME=c:\Progra~1\Java\<jdkdir></pre>
+
+ <p>The easiest solution, however, is to install JDK in a non-space directory, for example:</p>
+
+ <pre>c:\java\jdk1.7</pre>
+
+ <h2 id="DebugMode">Building in Debug Mode</h2>
+
+ <p>For immediate application testing and debugging, you can build your application in debug mode
+ and immediately install it on an emulator. In debug mode, the build tools automatically sign your
+ application with a debug key and optimize the package with {@code zipalign}.</p>
+
+ <p>To build in debug mode:</p>
+
+ <ol>
+ <li>Open a command-line and navigate to the root of your project directory.</li>
+ <li>Use Ant to compile your project in debug mode:
+ <pre>
+ant debug
+</pre>
+
+ <p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named
+ <code><your_project_name>-debug.apk</code>. The file is already signed with
+ the debug key and has been aligned with
+ <a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>.
+ </p>
+ </li>
+ </ol>
+
+ <p>Each time you change a source file or resource, you must run Ant again in order to package up
+ the latest version of the application.</p>
+
+ <p>To install and run your application on an emulator, see the following section about <a href=
+ "#RunningOnEmulator">Running on the Emulator</a>.</p>
+
+ <h2 id="ReleaseMode">Building in Release Mode</h2>
+
+ <p>When you're ready to release and distribute your application to end-users, you must build your
+ application in release mode. Once you have built in release mode, it's a good idea to perform
+ additional testing and debugging with the final .apk.</p>
+
+ <p>Before you start building your application in release mode, be aware that you must sign the
+ resulting application package with your private key, and should then align it using the {@code
+ zipalign} tool. There are two approaches to building in release mode: build an unsigned package
+ in release mode and then manually sign and align the package, or allow the build script to sign
+ and align the package for you.</p>
+
+ <h3 id="ManualReleaseMode">Build unsigned</h3>
+
+ <p>If you build your application <em>unsigned</em>, then you will need to manually sign and align
+ the package.</p>
+
+ <p>To build an <em>unsigned</em> .apk in release mode:</p>
+
+ <ol>
+ <li>Open a command-line and navigate to the root of your project directory.</li>
+
+ <li>Use Ant to compile your project in release mode:
+ <pre>
+ant release
+</pre>
+ </li>
+ </ol>
+
+ <p>This creates your Android application .apk file inside the project <code>bin/</code>
+ directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p>
+
+ <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't
+ be installed until signed with your private key.</p>
+
+ <p>Once you have created the unsigned .apk, your next step is to sign the .apk with your private
+ key and then align it with {@code zipalign}. To complete this procedure, read <a href=
+ "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
+
+ <p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users.
+ You should test the final build on different devices or AVDs to ensure that it
+ runs properly on different platforms.</p>
+
+ <h3 id="AutoReleaseMode">Build signed and aligned</h3>
+
+ <p>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 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.</p>
+
+ <p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that
+ you enter during the build process <strong>will be visible</strong>. If you are concerned about
+ your keystore and alias password being visible on screen, then you may prefer to perform the
+ application signing manually, via Jarsigner (or a similar tool). To instead perform the signing
+ procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with
+ <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
+
+ <p>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:</p>
+ <pre>
+key.store=path/to/my.keystore
+key.alias=mykeystore
+</pre>
+
+ <p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p>
+
+ <ol>
+ <li>Open a command-line and navigate to the root of your project directory.</li>
+
+ <li>Use Ant to compile your project in release mode:
+ <pre>
+ant release
+</pre>
+ </li>
+
+ <li>When prompted, enter you keystore and alias passwords.
+
+ <p class="caution"><strong>Caution:</strong> As described above, your password will be
+ visible on the screen.</p>
+ </li>
+ </ol>
+
+ <p>This creates your Android application .apk file inside the project <code>bin/</code>
+ directory, named <code><em><your_project_name></em>-release.apk</code>. This .apk file has
+ been signed with the private key specified in {@code ant.properties} and aligned with {@code
+ zipalign}. It's ready for installation and distribution.</p>
+
+ <h3 id="OnceBuilt">Once built and signed in release mode</h3>
+
+ <p>Once you have signed your application with a private key, you can install and run it on an
+ <a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. 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
+ <em>Settings > Applications > Unknown sources</em>.)</p>
+
+ <h2 id="RunningOnEmulator">Running on the Emulator</h2>
+
+ <p>Before you can run your application on the Android Emulator, you must <a href=
+ "{@docRoot}tools/devices/managing-avds.html">create an AVD</a>.</p>
+
+ <p>To run your application:</p>
+
+ <ol>
+ <li>
+ <strong>Open the AVD Manager and launch a virtual device</strong>
+
+ <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool
+with the <code>avd</code> options:</p>
+ <pre>
+android avd
+</pre>
+
+ <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p>
+ </li>
+
+ <li>
+ <strong>Install your application</strong>
+
+ <p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the
+ emulator:</p>
+ <pre>
+adb install <em><path_to_your_bin></em>.apk
+</pre>
+
+ <p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/}
+ directory after you build your application.</p>
+
+ <p>If there is more than one emulator running, you must specify the emulator upon which to
+ install the application, by its serial number, with the <code>-s</code> option. For
+ example:</p>
+ <pre>
+adb -s emulator-5554 install <em>path/to/your/app</em>.apk
+</pre>
+
+ <p>To see a list of available device serial numbers, execute {@code adb devices}.</p>
+ </li>
+ </ol>
+
+ <p>If you don't see your application on the emulator, try closing the emulator and launching the
+ virtual device again from the AVD Manager. Sometimes when you install an application for the
+ first time, it won't show up in the application launcher or be accessible by other applications.
+ This is because the package manager usually examines manifests completely only on emulator
+ startup.</p>
+
+ <p>Be certain to create multiple AVDs upon which to test your application. You should have one
+ AVD for each platform and screen type with which your application is compatible. For instance, if
+ your application compiles against the Android 4.0 (API Level 14) platform, you should create an
+ AVD for each platform equal to and greater than 4.0 and an AVD for each <a href=
+ "{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your
+ application on each one.</p>
+
+ <p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, you can
+ build your application and install it on the emulator in one simple step. Navigate to the root of
+ your project directory and use Ant to compile the project with <em>install mode</em>: <code>ant
+ install</code>. This will build your application, sign it with the debug key, and install it on
+ the currently running emulator.</p>
+
+ <h2 id="RunningOnDevice">Running on a Device</h2>
+
+ <p>Before you can run your application on a device, you must perform some basic setup for your
+ device:</p>
+
+ <ul>
+ <li>Enable <strong>USB debugging</strong> on your device.
+ <ul>
+ <li>On most devices running Android 3.2 or older, you can find the option under
+ <strong>Settings > Applications > Development</strong>.</li>
+ <li>On Android 4.0 and newer, it's in <strong>Settings > Developer options</strong>.
+ <p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer
+ options</strong> is hidden by default. To make it available, go
+ to <strong>Settings > About phone</strong> and tap <strong>Build number</strong>
+ seven times. Return to the previous screen to find <strong>Developer options</strong>.</p>
+ </li>
+ </ul>
+ </li>
+
+ <li>Ensure that your development computer can detect your device when connected via USB</li>
+ </ul>
+
+ <p>Read <a href="{@docRoot}tools/device.html#setting-up">Setting up a Device for
+ Development</a> for more information.</p>
+
+ <p>Once your device is set up and connected via USB, navigate to your SDK's <code>platform-tools/</code>
+ directory and install the <code>.apk</code> on the device:</p>
+ <pre>
+adb -d install <em>path/to/your/app</em>.apk
+</pre>
+
+ <p>The {@code -d} flag specifies that you want to use the attached device (in case you also have
+ an emulator running).</p>
+
+ <p>For more information on the tools used above, please see the following documents:</p>
+
+ <ul>
+ <li><a href="{@docRoot}tools/help/android.html">android Tool</a></li>
+
+ <li><a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a></li>
+
+ <li><a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (ADB)</li>
+ </ul>
+
+ <h2 id="Signing">Application Signing</h2>
+
+ <p>As you begin developing Android applications, understand that all Android applications must be
+ digitally signed before the system will install them on an emulator or device. There are two ways
+ to do this: with a <em>debug key</em> (for immediate testing on an emulator or development
+ device) or with a <em>private key</em> (for application distribution).</p>
+
+ <p>The Android build tools help you get started by automatically signing your .apk files with a
+ debug key at build time. This means that you can compile your application and install it on the
+ emulator without having to generate your own private key. However, please note that if you intend
+ to publish your application, you <strong>must</strong> sign the application with your own private
+ key, rather than the debug key generated by the SDK tools.</p>
+
+ <p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key,
+ prior to installing them on an emulator or development device. This means that you can quickly
+ run your application from Eclipse without having to generate your own private key. No specific
+ action on your part is needed, provided ADT has access to Keytool. However, please note that if
+ you intend to publish your application, you <strong>must</strong> sign the application with your
+ own private key, rather than the debug key generated by the SDK tools.</p>
+
+ <p>Please read <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your
+ Applications</a>, 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.</p>
+
+ <h2 id="AntReference">Ant Command Reference</h2>
+ <dt><code>ant clean</code></dt>
+ <dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code>
+(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a
+test project, the tested project is also cleaned.</dd>
+
+ <dt><code>ant debug</code></dt>
+ <dd>Builds a debug package. Works on application, library, and test projects and compiles
+ dependencies as needed.</dd>
+
+ <dt id="emma"><code>ant emma debug</code></dt>
+ <dd>Builds a test project while building the tested project with instrumentation turned on.
+ This is used to run tests with code coverage enabled.</dd>
+
+ <dt><code>ant release</code></dt>
+ <dd>Builds a release package.</dd>
+
+ <dt><code>ant instrument</code>
+ </dt>
+ <dd>Builds an instrumented debug package. This is generally called automatically when building a
+ test project with code coverage enabled (with the <code>emma</code>
+ target)</dd>
+
+ <dt><code>ant <build_target> install</code></dt>
+ <dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd>
+
+ <dt><code>ant installd</code></dt>
+ <dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not
+ already built.</dd>
+
+ <dt><code>ant installr</code></dt>
+ <dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not
+ already built.</dd>
+
+ <dt><code>ant installt</code></dt>
+ <dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the
+ tested application. This fails if the <code>.apk</code> is not already built.</dd>
+
+ <dt><code>ant installi</code></dt>
+ <dd>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 <code>.apk</code> is not already
+ built.</dd>
+
+ <dt><code>ant test</code></dt>
+ <dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be
+ previously installed.</dd>
+
+ <dt><code>ant debug installt test</code></dt>
+ <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
+ runs the tests.</dd>
+
+ <dt><code>ant emma debug install test</code></dt>
+ <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
+ runs the tests with code coverage enabled.</dd>
+
diff --git a/docs/html/tools/building/building-cmdline.jd b/docs/html/tools/building/building-cmdline.jd
index b65fc78..c1a0dd2 100644
--- a/docs/html/tools/building/building-cmdline.jd
+++ b/docs/html/tools/building/building-cmdline.jd
@@ -18,32 +18,37 @@
<li><a href="#RunningOnEmulator">Running on the Emulator</a></li>
<li><a href="#RunningOnDevice">Running on a Device</a></li>
<li><a href="#Signing">Application Signing</a></li>
- <li><a href="#AntReference">Ant Command Reference</a></li>
+ <li><a href="#GradleReference">Gradle Command Reference</a></li>
</ol>
<h2>See also</h2>
<ol>
- <li><a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from
-the Command Line</a></li>
- <li><a href="{@docRoot}tools/devices/emulator.html">Using the Android
-Emulator</a></li>
- <li><a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a></li>
+ <li><a href="{@docRoot}sdk/installing/studio-build.html">
+ Build System</a></li>
+ <li><a href="{@docRoot}tools/devices/managing-avds-cmdline.html">
+ Managing AVDs from the Command Line</a></li>
+ <li><a href="{@docRoot}tools/devices/emulator.html">
+ Using the Android Emulator</a></li>
+ <li><a href="{@docRoot}tools/publishing/app-signing.html">
+ Signing Your Applications</a></li>
</ol>
</div>
</div>
- <p>There are two ways to build your application using the Ant build script: one for
- testing/debugging your application — <em>debug mode</em> — and one for building your
- final package for release — <em>release mode</em>. Regardless of which way you build your application,
- it must be signed before it can install on an emulator or device—with a debug key when building
- in debug mode and with your own private key when building in release mode.</p>
+ <p>By default, there are two build types to build your application using the gradle.build settings:
+ one for debugging your application — <em>debug</em> — and one for building your
+ final package for release — <em>release mode</em>. Regardless of which way you build type
+ your modules use, the app must be signed before it can install on an emulator or device—with
+ a debug key when building in debug mode and with your own private key when building in release mode.</p>
- <p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile
- and build your project. This will create the .apk file that you can install on an emulator or device.
- When you build in debug mode, the .apk file is automatically signed by the SDK tools with
- a debug key, so it's instantly ready for installation onto an emulator or attached
+ <p>Whether you're building with the debug or release build type, you need to run
+ and build your module. This will create the .apk file that you can install on an emulator or device.
+ When you build using the debug build type, the .apk file is automatically signed by the SDK tools
+ with a debug key based on the <code>debuggable true</code> setting in the module's gradle.build file,
+ so it's instantly ready for installation onto an emulator or attached
development device. You cannot distribute an application that is signed with a debug key.
- When you build in release mode, the .apk file is <em>unsigned</em>, so you
- must manually sign it with your own private key, using Keytool and Jarsigner.</p>
+ When you build using the release build type, the .apk file is <em>unsigned</em>, so you
+ must manually sign it with your own private key, using Keytool and Jarsigner settings in the
+ module's gradle.build file.</p>
<p>It's important that you read and understand <a href=
"{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>, particularly once
@@ -52,7 +57,7 @@
getting started, however, you can quickly run your applications on an emulator or your own
development device by building in debug mode.</p>
- <p>If you don't have Ant, you can obtain it from the <a href="http://ant.apache.org/">Apache Ant
+ <p>If you don't have <a href="http://www.gradle.org/">Gradle</a>, you can obtain it from the <a href="http://gradle.org/">Gradle
home page</a>. Install it and make sure it is in your executable PATH. Before calling Ant, you
need to declare the JAVA_HOME environment variable to specify the path to where the JDK is
installed.</p>
@@ -64,7 +69,7 @@
<p>The easiest solution, however, is to install JDK in a non-space directory, for example:</p>
- <pre>c:\java\jdk1.6.0_02</pre>
+ <pre>c:\java\jdk1.7</pre>
<h2 id="DebugMode">Building in Debug Mode</h2>
@@ -72,28 +77,46 @@
and immediately install it on an emulator. In debug mode, the build tools automatically sign your
application with a debug key and optimize the package with {@code zipalign}.</p>
- <p>To build in debug mode:</p>
+ <p>To build in debug mode, open a command-line and navigate to the root of your project directory.
+ Use Gradle to build your project in debug mode, invoke the <code>assembleDebug</code> build task
+ using the Gradle wrapper script (<code>gradlew assembleRelease</code>).
- <ol>
- <li>Open a command-line and navigate to the root of your project directory.</li>
- <li>Use Ant to compile your project in debug mode:
- <pre>
-ant debug
+ <p>This creates your debug <code>.apk</code> file inside the module <code>build/</code>
+ directory, named <code><your_module_name>-debug.apk</code>. The file is already signed
+ with the debug key and has been aligned with
+ <a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>. </p>
+
+ <p>On Windows platforms, type this command:</p>
+
+<pre>
+> gradlew.bat assembleDebug
</pre>
- <p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named
- <code><your_project_name>-debug.apk</code>. The file is already signed with
- the debug key and has been aligned with
- <a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>.
- </p>
- </li>
- </ol>
+<p>On Mac OS and Linux platforms, type these commands:</p>
- <p>Each time you change a source file or resource, you must run Ant again in order to package up
+<pre>
+$ chmod +x gradlew
+$ ./gradlew assembleDebug
+</pre>
+
+ <p>The first command (<code>chmod</code>) adds the execution permission to the Gradle wrapper
+ script and is only necessary the first time you build this project from the command line.</p>
+
+ <p>After you build the project, the output APK for the app module is located in
+ <code>app/build/outputs/apk/</code>, and the output AAR for any lib modules is located in
+ <code>lib/build/outputs/libs/</code>.</p>
+
+ <p>To see a list of all available build tasks for your project, type this command:</p>
+
+<pre>
+$ ./gradlew tasks
+</pre>
+
+ <p>Each time you change a source file or resource, you must run Gradle again in order to package up
the latest version of the application.</p>
- <p>To install and run your application on an emulator, see the following section about <a href=
- "#RunningOnEmulator">Running on the Emulator</a>.</p>
+ <p>To install and run your application on an emulator, see the section about <a href=
+ "{@docRoot}tools/building/building-studio.html">Running on the Emulator</a>.</p>
<h2 id="ReleaseMode">Building in Release Mode</h2>
@@ -112,20 +135,24 @@
<p>If you build your application <em>unsigned</em>, then you will need to manually sign and align
the package.</p>
- <p>To build an <em>unsigned</em> .apk in release mode:</p>
+ <p>To build an <em>unsigned</em> .apk in release mode, open a command-line and navigate to the
+ root of your module directory. Invoke the <code>assembleRelease</code> build task.</li>
- <ol>
- <li>Open a command-line and navigate to the root of your project directory.</li>
+ <p>On Windows platforms, type this command:</p>
- <li>Use Ant to compile your project in release mode:
- <pre>
-ant release
+<pre>
+> gradlew.bat assembleRelease
</pre>
- </li>
- </ol>
+
+<p>On Mac OS and Linux platforms, type this command:</p>
+
+<pre>
+$ ./gradlew assembleRelease
+</pre>
+
<p>This creates your Android application .apk file inside the project <code>bin/</code>
- directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p>
+ directory, named <code><em><your_module_name></em>-unsigned.apk</code>.</p>
<p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't
be installed until signed with your private key.</p>
@@ -142,34 +169,47 @@
<p>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 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.</p>
+ your key alias in your modules's build.gradle file. With this information provided,
+ the build will prompt you for your keystore and alias password when you build using the release
+ build type and produce your final application package, which will be ready for distribution.</p>
- <p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that
- you enter during the build process <strong>will be visible</strong>. If you are concerned about
- your keystore and alias password being visible on screen, then you may prefer to perform the
- application signing manually, via Jarsigner (or a similar tool). To instead perform the signing
- procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with
- <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
-
- <p>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}.
+ <p>To specify your keystore and alias, open the module gradle.build file (found in
+ the root of the module directory) and add entries for {@code storeFile}, {@code storePassword},
+ {@code keyAlias} and {@code keyPassword}.
For example:</p>
<pre>
-key.store=path/to/my.keystore
-key.alias=mykeystore
+storeFile file("myreleasekey.keystore")
+keyAlias "MyReleaseKey"
</pre>
<p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p>
<ol>
- <li>Open a command-line and navigate to the root of your project directory.</li>
+ <li>Open a command-line and navigate to the root of your module directory.</li>
- <li>Use Ant to compile your project in release mode:
- <pre>
-ant release
-</pre>
+ <li>Edit the gradle.build file to build your project in release mode:
+ <p><pre>
+...
+android {
+ ...
+ defaultConfig { ... }
+ signingConfigs {
+ release {
+ storeFile file("myreleasekey.keystore")
+ storePassword "password"
+ keyAlias "MyReleaseKey"
+ keyPassword "password"
+ }
+ }
+ buildTypes {
+ release {
+ ...
+ signingConfig signingConfigs.release
+ }
+ }
+}
+...
+</pre></p>
</li>
<li>When prompted, enter you keystore and alias passwords.
@@ -179,9 +219,9 @@
</li>
</ol>
- <p>This creates your Android application .apk file inside the project <code>bin/</code>
- directory, named <code><em><your_project_name></em>-release.apk</code>. This .apk file has
- been signed with the private key specified in {@code ant.properties} and aligned with {@code
+ <p>This creates your Android application .apk file inside the module <code>build/</code>
+ directory, named <code><em><your_module_name></em>-release.apk</code>. This .apk file has
+ been signed with the private key specified in gradle.build file and aligned with {@code
zipalign}. It's ready for installation and distribution.</p>
<h3 id="OnceBuilt">Once built and signed in release mode</h3>
@@ -222,7 +262,7 @@
adb install <em><path_to_your_bin></em>.apk
</pre>
- <p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/}
+ <p>Your .apk file (signed with either a release or debug key) is in your module {@code build/}
directory after you build your application.</p>
<p>If there is more than one emulator running, you must specify the emulator upon which to
@@ -307,75 +347,25 @@
device) or with a <em>private key</em> (for application distribution).</p>
<p>The Android build tools help you get started by automatically signing your .apk files with a
- debug key at build time. This means that you can compile your application and install it on the
+ debug key at build time. This means that you can build your application and install it on the
emulator without having to generate your own private key. However, please note that if you intend
to publish your application, you <strong>must</strong> sign the application with your own private
key, rather than the debug key generated by the SDK tools.</p>
- <p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key,
+ <p>Android Studio helps you get started quickly by signing your .apk files with a debug key,
prior to installing them on an emulator or development device. This means that you can quickly
- run your application from Eclipse without having to generate your own private key. No specific
- action on your part is needed, provided ADT has access to Keytool. However, please note that if
- you intend to publish your application, you <strong>must</strong> sign the application with your
- own private key, rather than the debug key generated by the SDK tools.</p>
+ run your application from Android Studio without having to generate your own private key. No
+ specific action on your part is needed, provided ADT has access to Keytool. However, please note
+ that if you intend to publish your application, you <strong>must</strong> sign the application
+ with your own private key, rather than the debug key generated by the SDK tools.</p>
<p>Please read <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your
Applications</a>, 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.</p>
+ means to you as an Android application developer. The document also includes a guide to publishing
+ and signing your application.</p>
- <h2 id="AntReference">Ant Command Reference</h2>
- <dt><code>ant clean</code></dt>
- <dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code>
-(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a
-test project, the tested project is also cleaned.</dd>
+ <h2 id="Grad;eReference">Gradle Build Language Reference</h2>
- <dt><code>ant debug</code></dt>
- <dd>Builds a debug package. Works on application, library, and test projects and compiles
- dependencies as needed.</dd>
-
- <dt id="emma"><code>ant emma debug</code></dt>
- <dd>Builds a test project while building the tested project with instrumentation turned on.
- This is used to run tests with code coverage enabled.</dd>
-
- <dt><code>ant release</code></dt>
- <dd>Builds a release package.</dd>
-
- <dt><code>ant instrument</code>
- </dt>
- <dd>Builds an instrumented debug package. This is generally called automatically when building a
- test project with code coverage enabled (with the <code>emma</code>
- target)</dd>
-
- <dt><code>ant <build_target> install</code></dt>
- <dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd>
-
- <dt><code>ant installd</code></dt>
- <dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not
- already built.</dd>
-
- <dt><code>ant installr</code></dt>
- <dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not
- already built.</dd>
-
- <dt><code>ant installt</code></dt>
- <dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the
- tested application. This fails if the <code>.apk</code> is not already built.</dd>
-
- <dt><code>ant installi</code></dt>
- <dd>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 <code>.apk</code> is not already
- built.</dd>
-
- <dt><code>ant test</code></dt>
- <dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be
- previously installed.</dd>
-
- <dt><code>ant debug installt test</code></dt>
- <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
- runs the tests.</dd>
-
- <dt><code>ant emma debug install test</code></dt>
- <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
- runs the tests with code coverage enabled.</dd>
+<p> See the <a href="http://gradle.org/docs/current/dsl/index.html">Gradle Build Language Reference</a> for a complete list and description of the Gradle Domain Specific Language (DSL) and declarative
+language elements.</p>
diff --git a/docs/html/tools/building/building-studio.jd b/docs/html/tools/building/building-studio.jd
new file mode 100644
index 0000000..cb8cc50
--- /dev/null
+++ b/docs/html/tools/building/building-studio.jd
@@ -0,0 +1,256 @@
+page.title=Building and Running from Android Studio
+parent.title=Building and Running
+parent.link=index.html
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#buildProject">Building your Project in Android Studio</a>
+ <ol>
+ <li><a href="#buildRelease">Build a release version</a> </li>
+ </ol>
+ </li>
+ <li><a href=id="RunningApp">Running your App</a>
+ <ol>
+ <li><a href="#RunConfig">Creating a Run Configuration</a></li>
+ <li><a href="#AutoAndManualTargetModes">Automatic and manual target modes</a></li>
+ <li><a href="#RunningOnEmulatorStudio">Running on an Emulator</a></li>
+ <li><a href="#RunningOnDeviceStudio">Running on a Device</a></li>
+ </ol>
+ </li>
+ </ol>
+
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}sdk/installing/studio-build.html">
+ Build System</a></li>
+ <li><a href="{@docRoot}tools/devices/managing-avds.html">
+ Managing AVDs with AVD Manager</a></li>
+ <li><a href="{@docRoot}tools/devices/emulator.html">
+ Using the Android Emulator</a></li>
+ <li><a href="{@docRoot}tools/publishing/app-signing.html">
+ Signing Your Applications</a></li>
+ </ol>
+
+ </div>
+</div>
+
+
+<p>This document shows you how to use Android Studio to build an application <code>.apk</code> for
+testing or release and how to run your application on an emulator or a real device.</p>
+
+
+<h2 id="buildProject">Build your Project in Android Studio</h2>
+
+<p>To build the project on Android Studio, click <strong>Build</strong> and select
+<strong>Make Project</strong>. The status bar at the bottom of the window shows the current
+progress of the build:</p>
+
+<p><code>Gradle: Executing tasks: [:app:assembleDebug, :lib:bundleDebug]</code></p>
+
+<p>Click <img src="{@docRoot}images/tools/as-gradlebutton.png" alt=""
+style="vertical-align:bottom;margin:0;"/> on the bottom
+right part of the window to show the <em>Gradle Console</em>, as shown in figure 2.</p>
+
+<img src="{@docRoot}images/tools/as-gradleconsole.png" alt="" />
+<p class="img-caption"><strong>Figure 2.</strong> The Gradle Console in Android Studio.</p>
+
+<p>The Gradle Console shows the build tasks and subtasks that the build system runs for
+Android Studio. If the build fails, you can find more details on the console. To hide the Gradle
+Console, click <img src="{@docRoot}images/tools/as-gradlebutton.png" alt=""
+style="vertical-align:bottom;margin:0;"/> again.</p>
+
+<p class="note">If your project uses product flavors, Android Studio invokes the task for the
+selected build variant. For more information, see the
+<a href="{@docRoot}sdk/installing/studio-build.html">Build System</a> guide.</p>
+
+<p>To view the list of all available build tasks in Android Studio, click <strong>Gradle</strong>
+on the right side of the IDE window. The <em>Gradle tasks</em> panel appears as shown in
+figure 3. Double-click any build task to run it in Android Studio. To hide the <em>Gradle tasks</em>
+panel, click <strong>Gradle</strong> again.</p>
+
+<img src="{@docRoot}images/tools/as-gradlepanel.png" alt="" />
+<p class="img-caption"><strong>Figure 3.</strong> The list of build tasks in Android Studio.</p>
+
+<h3 id="buildRelease">Build a release version</h3>
+
+<p>You can now build the release version of your application for distribution. To build it from Android
+Studio:</p>
+
+<ol>
+ <li>Click <strong>Gradle</strong> on the right side of the IDE window.</li>
+ <li>On the <em>All tasks</em> section of the sidebar that appears, expand
+ <strong>BuildSystemExample</strong>.</li>
+ <li>Expand <strong>:app</strong> and double-click <strong>assembleRelease</strong>.</li>
+</ol>
+
+<p>You can use this procedure to invoke any build task from Android Studio.</p>
+
+<p>The build generates an APK for each build variant:
+the <code>app/build/apk/</code> directory contains packages named
+<code>app-<flavor>-<buildtype>.apk</code>; for example, <code>app-full-release.apk</code> and
+<code>app-demo-debug.apk</code>.</p>
+
+
+<p>For more build system information, see
+<a href="{@docRoot}sdk/installing/studio-build.html">Build System</a>.</p>
+
+
+ <h2 id="RunningApp">Running your app</h2>
+
+ <p>This section shows you how to run your application on an emulator or a real device
+ from Android Studio—all of which is done using the debug version of your application.
+ For more information about how to sign your application with a private key for release, see
+ <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a></p>
+
+
+ <h3 id="RunConfig">Creating a Run Configuration</h3>
+
+ <p>The run configuration specifies the module to run, package to deploy, Activity to start,
+ target device, emulator settings, and Logcat options. Run configuration can be set at the project,
+ default, and module levels. When you first run a module as an <em>Android Application</em>,
+ Android Studio will automatically create a run configuration. The default run
+ configuration will launch the default project Activity and use automatic target mode for device
+ selection (with no preferred AVD). If the default settings don't suit your project or module, you
+ can customize the run configuration or even create a new one.</p>
+
+ <p>To create or modify a run configuration, see the IntelliJ documentation on
+ <a href="https://www.jetbrains.com/idea/webhelp/run-debug-configuration-android-application.html">
+ Run/Debug configurations</a>.</p>
+
+ <p>The following steps highlight the important things you need to do for an Android project:</p>
+
+ <ol>
+ <li>Open <strong>Edit</strong> Configurations from the <strong>Run</strong> Menu.</li>
+
+ <li>Expand the <strong>Android Application</strong> item and create a new configuration or open
+ an existing one.</li>
+
+ <li>With the Run Configuration selected, adjust your desired run configuration settings:
+ <ul>
+ <li>In the General tab, specify the Module settings to launch. In Target tab, consider whether
+ you'd like to use Manual or Automatic mode when selecting an AVD to run your application. See
+ the following section on <a href="#AutoAndManualTargetModes">Automatic and manual target modes</a>).
+ </li>
+ <li>In the Emulator tab, specify any emulator options to the Additional Emulator Command Line
+ Options field. For example, you could add <code>-scale 96dpi</code> to scale the AVD's screen
+ to an accurate size, based on the dpi of your computer monitor. For a full list of emulator
+ options, see the <a href="{@docRoot}tools/help/emulator.html">Android
+ Emulator</a> document.</p>
+ </li>
+ <li>In the Logcat tab, set the LogCat options for the application. </li>
+ </ul>
+ </li>
+ </ol>
+
+
+ <h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3>
+
+ <p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to
+ select an AVD. In this mode, Android Studio will select an AVD for the application in the following
+ manner:</p>
+
+ <ol>
+ <li>If there's a device or emulator already running and its AVD configuration meets the
+ requirements of the application's build target, the application is installed and run upon
+ it.</li>
+
+ <li>If there's more than one device or emulator running, each of which meets the requirements
+ of the build target, a device chooser is shown to let you select which device to use.</li>
+
+ <li>If there are no devices or emulators running that meet the requirements of the build
+ target, Android Studio looks at the available AVDs. If there is an AVD that matches the build
+ target of the project, Android Studio chooses that AVD. If the AVD versions are newer than the
+ build target of the project, Android Studio chooses the oldest possible version of an AVD that
+ meets the project or module build target requirement.</li>
+
+ <li>If there are no suitable AVDs, the application is not installed and a console error warning
+ tells you that there is no existing AVD that meets the build target requirements.</li>
+ </ol>
+
+ <p>However, if a "preferred" AVD is selected in the run configuration, then the application will
+ <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator will be
+ launched.</p>
+
+ <p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" is
+ presented every time that your application is run, so that you can select which AVD to use.</p>
+
+
+
+ <h3 id="RunningOnEmulatorStudio">Running on the emulator</h3>
+
+ <p>Before you can run your application on the Android Emulator, you verify the default AVD or
+ <a href="{@docRoot}tools/devices/managing-avds.html">create an AVD</a>.</p>
+
+ <p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or
+ <strong>Run</strong> > <strong>debug</strong>) from the Android Studio menu bar. Android Studio
+ automatically creates a default run configuration for the project. Android Studio will then perform
+ the following:</p>
+
+ <ol>
+ <li>Compile the project (if there have been changes since the last build).</li>
+
+ <li>Create a default run configuration (if one does not already exist for the project).</li>
+
+ <li>Install and start the application on an emulator (or device), based on the Deployment
+ Target defined by the run configuration.
+
+ <p>By default, Android run configurations use an "automatic target" mode for selecting a
+ device target. For information on how automatic target mode selects a deployment target, see
+ <a href="#AutoAndManualTargetModes">Automatic and manual target modes</a> above.</p>
+ </li>
+ </ol>
+
+ <p>If you run the application with <strong>Debug</strong>, the <em>Choose a Device</em> option
+ appears so you can select an attached device or emulator. Once the device or emulator is selected,
+ Android Studio opens the Debug console and starts the application's main activity. Otherwise, if
+ you run the application with the normal Run command, Android Studio installs the application on the
+ device and launches the main activity.</p>
+
+ <p>To set or change the run configuration used for your project or module, select
+ <strong>Run</strong> > <strong>Edit Configurations</strong>. See the section below about
+ <a href="#RunConfig">Creating a Run Configuration</a> for more information.</p>
+
+ <p>Be certain to create multiple AVDs upon which to test your application. You should have one
+ AVD for each platform and screen type with which your application is compatible. For instance, if
+ your application compiles against the Android 4.0 (API Level 14) platform, you should create an
+ AVD for each platform equal to and greater than 4.0 and an AVD for each <a href=
+ "{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your
+ application on each one.</p>
+
+ <h3 id="RunningOnDeviceStudio">Running on a device</h3>
+
+ <p>Before you can run your application on a device, you must perform some basic setup for your
+ device:</p>
+
+ <ul>
+ <li>Ensure that your application is debuggable by setting the
+ <code>android:debuggable</code> attribute of the <code><application></code>
+ element to <code>true</code> in the build.gradle file. </li>
+
+ <li>Enable <strong>USB debugging</strong> on your device.
+ <ul>
+ <li>On most devices running Android 3.2 or older, you can find the option under
+ <strong>Settings > Applications > Development</strong>.</li>
+ <li>On Android 4.0 and newer, it's in <strong>Settings > Developer options</strong>.
+ <p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer
+ options</strong> is hidden by default. To make it available, go
+ to <strong>Settings > About phone</strong> and tap <strong>Build number</strong>
+ seven times. Return to the previous screen to find <strong>Developer options</strong>.</p>
+ </li>
+ </ul>
+ </li>
+
+ <li>Ensure that your development computer can detect your device when connected via USB</li>
+ </ul>
+
+ <p>Read <a href="{@docRoot}tools/device.html">Using Hardware Devices</a>
+ for more information.</p>
+
+ <p>Once set up and your device is connected via USB, install your application on the device by
+ selecting <strong>Run</strong> > <strong>Run</strong> (or <strong>Run</strong> >
+ <strong>Debug</strong>) from the Android Studio menu bar.</p>
+
+
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>
diff --git a/docs/html/tools/building/index.jd b/docs/html/tools/building/index.jd
index c1f3019..6428e73 100644
--- a/docs/html/tools/building/index.jd
+++ b/docs/html/tools/building/index.jd
@@ -1,92 +1,40 @@
-page.title=Building and Running
+page.title=Building and Running Overview
@jd:body
<div id="qv-wrapper">
- <div id="qv">
- <h2>In this document</h2>
- <ol>
- <li><a href="#detailed-build">A Detailed Look at the Build Process</a></li>
- </ol>
- </div>
- </div>
-
- <p>During the build process, your Android projects are compiled and packaged into an .apk file,
- the container for your application binary. It contains all of the information necessary to run
- your application on a device or emulator, such as compiled <code>.dex</code> files (<code>.class</code> files
- converted to Dalvik byte code), a binary version of the <code>AndroidManifest.xml</code> file, compiled
- resources (<code>resources.arsc</code>) and uncompiled resource files for your application.</p>
+<div id="qv">
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}tools/building/building-studio.html">
+ Building Your Project from Android Studio</a></li>
+ <li><a href="{@docRoot}tools/building/building-cmdline.html">
+ Building Your Project from the Command Line</a></li>
+ <li><a href="{@docRoot}sdk/building/studio-build.html">
+ Build System</a></li>
+ </ol>
+</div>
+</div>
- <p>If you are developing in Eclipse, the ADT plugin incrementally builds your project as you
- make changes to the source code. Eclipse outputs an <code>.apk</code> file automatically to the bin folder of
- the project, so you do not have to do anything extra to generate the <code>.apk</code>.</p>
- <p>If you are developing in a non-Eclipse environment, you can build your project with the
- generated <code>build.xml</code> Ant file that is in the project directory. The Ant file calls targets that
- automatically call the build tools for you.</p>
+<p>The Android build process provides project and module build settings so that
+your Android modules are compiled and packaged into <code>.apk</code> files, the containers
+for your application binaries, based on your build settings. The apk file for each app contains all
+of the information necessary to run your application on a device or emulator, such as compiled
+<code>.dex</code> files (<code>.class</code> files converted to Dalvik byte code), a binary version
+of the <code>AndroidManifest.xml</code> file, compiled resources (<code>resources.arsc</code>) and
+uncompiled resource files for your application.</p>
- <p>To run an application on an emulator or device, the application must be signed using debug or
- release mode. You typically want to sign your application in debug mode when you develop and test
- your application, because the build tools use a debug key with a known password so you do not have
- to enter it every time you build. When you are ready to release the application to Google
- Play, you must sign the application in release mode, using your own private key.</p>
+<p>To run an application on an emulator or device, the application must be signed using debug or
+release mode. You typically want to sign your application in debug mode when you develop and test
+your application, because the build system uses a debug key with a known password so you do not have
+to enter it every time you build. When you are ready to release the application to Google
+Play, you must sign the application in release mode, using your own private key.</p>
- <p>Fortunately, Eclipse or your Ant build script signs the application for you in debug mode
- when you build your application. You can also easily setup Eclipse or your Ant build to sign your
- application in release mode as well. For more information on signing applications, see <a href=
- "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
-
- <p>The following diagram depicts the components involved in building and running an application:</p>
+<p>If you are using Android development tools, the build system can sign the application for you
+when build your app for debugging. You must obtain a certificate to sign your app when you build
+and app for release. For more information on signing applications, see
+<a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
- <img src="{@docRoot}images/build-simplified.png" />
+<p>The following diagram depicts the components involved in building and running an application:</p>
- <h2 id="detailed-build">A Detailed Look at the Build Process</h2>
-
- <p>The build process involves many tools and processes that generate intermediate files on the
- way to producing an <code>.apk</code>. If you are developing in Eclipse, the complete build process is
- automatically done periodically as you develop and save your code changes. If you are using other
- IDEs, this build process is done every time you run the generated Ant build script for your
- project. It is useful, however, to understand what is happening under the hood since much of the
- tools and processes are masked from you. The following diagram depicts the different tools and
- processes that are involved in a build:</p>
-
- <img src="{@docRoot}images/build.png" />
-
- <p>The general process for a typical build is outlined below:</p>
-
- <ul>
-
- <li>The Android Asset Packaging Tool (aapt) takes your application resource files, such as the
- <code>AndroidManifest.xml</code> file and the XML files for your Activities, and compiles them. An <code>R.java</code> is
- also produced so you can reference your resources from your Java code.</li>
-
- <li>The aidl tool converts any <code>.aidl</code> interfaces that you have into Java interfaces.</li>
-
- <li>All of your Java code, including the <code>R.java</code> and <code>.aidl</code> files, are compiled by the Java
- compiler and .class files are output.</li>
-
- <li>The dex tool converts the .class files to Dalvik byte code. Any 3rd party libraries and
- .class files that you have included in your project are also converted into <code>.dex</code> files so that
- they can be packaged into the final <code>.apk</code> file.</li>
-
- <li>All non-compiled resources (such as images), compiled resources, and the .dex files are
- sent to the apkbuilder tool to be packaged into an <code>.apk</code> file.</li>
-
- <li>Once the <code>.apk</code> is built, it must be signed with either a debug or release key before it can
- be installed to a device.</li>
-
- <li>Finally, if the application is being signed in release mode, you must align the <code>.apk</code> with
- the zipalign tool. Aligning the final <code>.apk</code> decreases memory usage when the application is
- running on a device.</li>
- </ul>
-
-<p class="note"><b>Note:</b> Apps are limited to a 64K method reference limit. If your app reaches
-this limit, the build process outputs the following error message:
-
-<pre>Unable to execute dex: method ID not in [0, 0xffff]: 65536.</pre>
-
-To avoid this, you can
-<a href="http://android-developers.blogspot.com.es/2011/07/custom-class-loading-in-dalvik.html">load
-secondary dex files at runtime</a> and use
-<a href="http://developer.android.com/tools/help/proguard.html">ProGuard</a> to strip out unnecessary
-class references (Proguard only works when building in release mode).
-</p>
\ No newline at end of file
+<img src="{@docRoot}images/build-simplified.png" />
diff --git a/docs/html/tools/building/plugin-for-gradle.jd b/docs/html/tools/building/plugin-for-gradle.jd
new file mode 100644
index 0000000..b479ed8
--- /dev/null
+++ b/docs/html/tools/building/plugin-for-gradle.jd
@@ -0,0 +1,448 @@
+page.title=Android Plug-in for Gradle
+
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+<h2>In this document</h2>
+<ol>
+ <li><a href="#workBuildVariants">Work with build variants</a></li>
+</ol>
+
+
+<h2>See also</h2>
+<ul>
+<li><a href="{@docRoot}sdk/installing/studio-build.html">
+Build System Overview</a></li>
+<li><a href="{@docRoot}tools/building/index.html">
+Buidling and Running</a></li>
+<li><a href="{@docRoot}tools/building/building-studio.html">
+Building and Running from Android Studio</a></li>
+</ul>
+
+<h2>Download</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/sdk-tools/android-gradle-plugin-dsl.zip"
+ class="button">Plugin Command Reference</a>
+ <p class="filename">android-gradle-plugin-dsl.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>The Android build system consists of an Android plugin for <em>Gradle</em>.
+<a href="http://www.gradle.org/">Gradle</a> is an advanced build toolkit that manages
+dependencies and allows you to define custom build logic. Android Studio uses a Gradle wrapper
+to fully integrate the Android plugin for Gradle. The Android plugin for Gradle also runs
+independent of Android Studio. This means that you can build your Android apps from which Android
+Studio and from the command line on your machine or on machines where Android Studio is not installed
+(such as continuous integration servers).</p>
+
+<p>The output of the build is the same whether you are building a project from the command line,
+on a remote machine, or using Android Studio.</p>
+
+<h2 id="buildConf">Build configuration</h2>
+
+<p>The build configuration for your project is defined inside <code>build.gradle</code> files,
+which are plain text files that use the syntax and options from Gradle and the Android plugin
+to configure the following aspects of your build:</p>
+
+<ul>
+ <li><em>Build variants</em>. The build system can generate multiple APKs with different
+ product and build configurations for the same module. This is useful when you want to
+ build different versions of your application without having to create a separate projects
+ or modules for each version.</li>
+ <li><em>Dependencies</em>. The build system manages project dependencies and supports
+ dependencies from your local filesystem and from remote repositories. This prevents you
+ from having to search, download, and copy binary packages for your dependencies into your
+ project directory.</li>
+ <li><em>Manifest entries</em>. The build system enables you to specify values for some
+ elements of the manifest file in the build variant configuration. These build values
+ override the existing values in the manifest file. This is useful if you want to generate
+ multiple APKs for your modules where each of the <code>apk</code> files has a different
+ application name, minimum SDK version, or target SDK version. When multiple manifests are
+ present, manifest settings are merged in priority of buildType and productFlavor,
+ <code>/main</code> manifest, and the library manifests.</li>
+ <li><em>Signing</em>. The build system enables you to specify signing settings in the build
+ configuration, and it can sign your APKs during the build process.</li>
+ <li><em>ProGuard</em>. The build system enables you to specify a different
+ <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> rules
+ file for each build variant. The build system can run ProGuard to obfuscate your classes
+ during the build process.</li>
+ <li><em>Testing</em>. For most templates, the build system creates a test directory,
+ <em>androidTest</em> and generates a test APK from the test sources in your project, so
+ you do not have to create a separate test project. The build system can also run your tests
+ during the build process.</li>
+</ul>
+
+<p>Gradle build files use Domain Specific Language (DSL) to describe and manipulate the build logic
+through <em>Groovy</em> syntax. <a href="http://groovy.codehaus.org/">Groovy</a> is a dynamic
+language that you can use to define custom build logic and to interact with the Android-specific
+elements provided by the Android plugin for Gradle.</p>
+
+<h2 id="buildConv">Build by convention</h2>
+
+<p>The Android Studio build system assumes <em>sensible defaults</em> for the project structure
+and other build options. If your project adheres to these conventions, your Gradle build files are
+very simple. When some of these conventions do not apply to your project, the flexibility of the
+build system allows you to configure almost every aspect of the build process. For example, if
+you need to replace the default source folders in your module directories, you can configure a new
+directory structure in the module's build file. </p>
+
+<h2 id="projectModules">Projects and modules build settings</h2>
+
+<p>A <em>project</em> in Android Studio represents the top-level Android development structure.
+Android Studio projects contain project files and one or more application modules. A
+<em>module</em> is a component of your app that you can build, test, or debug independently.
+Modules contain the source code and resources for your apps. Android Studio projects can contain
+several kinds of modules:</p>
+
+<ul>
+ <li><em>Android application modules</em> contain application (mobile, TV, Wear, Glass) code and
+ may depend on library modules, although many Android apps consists of only one application
+ module. The build system generates APK packages for application modules. </li>
+ <li><em>Android library modules</em> contain reusable Android-specific code and resources.
+ The build system generates an AAR (Android ARchive) package for library modules.</li>
+ <li><em>App Engine modules</em> contain code and resources for App Engine integration.</li>
+ <li><em>Java library modules</em> contain reusable code. The build system generates a
+ JAR package for Java library modules.</li>
+</ul>
+
+<p>Android Studio projects contain a top-level project Gradle build file that allows you to add the
+configuration options common to all application modules in the project. Each application module
+also has its own build.gradle file for build settings specific to that module.</p>
+
+<h3>Project Build File</h3>
+<p>By default, the project-level Gradle file uses <em>buildscript</em> to define the Gradle
+<em>repositories</em> and <em>dependencies</em>. This allows different projects to use different
+Gradle versions. Supported repositories include JCenter, Maven Central, or Ivy. This example
+declares that the build script uses the JCenter repository and a classpath dependency artifact
+that contains the Android plugin for Gradle version 0.14.4.
+</p>
+<p>
+<pre>
+buildscript {
+ repositories {
+ jcenter()
+ }
+ dependencies {
+ classpath 'com.android.tools.build:gradle:0.14.4'
+
+ // NOTE: Do not place your application dependencies here: they belong
+ // in the individual module build.gradle files
+ }
+}
+
+allprojects {
+ repositories {
+ jcenter()
+ }
+}
+</pre>
+
+<p class="note"><strong>Note:</strong> The SDK location for the Android Studio project is defined in
+the <em>local.properties</em> file in the <code>sdk.dir<sdk location></code> setting or through an
+<code>ANDROID_HOME</code> environment variable.</p>
+
+<h3>Module Build File</h3>
+<p>The application module Gradle build file allows you to configure module build settings,
+including overriding the <code>src/main</code> manifest settings and setting custom packaging
+options. </p>
+
+<ul>
+ <li>android settings </li>
+ <ul>
+ <li>compileSdkVersion</li>
+ <li>buildToolsVersion</li>
+ </ul>
+
+ <li>defaultConfig and productFlavors </li>
+ <ul>
+ <li>manifest properties such as applicationId, minSdkVersion, targetSdkVersion, and test
+ information</li>
+ </ul>
+
+ <li>buildTypes</li>
+ <ul>
+ <li>build properties such as debuggable, ProGuard enabling, debug signing, version name
+ suffix and testinformation</li>
+ </ul>
+
+ <li>dependencies</li>
+</ul>
+
+<p>This example applies the Android plugin, uses the default configuration to override several
+manifest properties, creates two build types: release and debug, and declares several dependencies.
+</p>
+
+<pre>
+apply plugin: 'com.android.application'
+
+android {
+ compileSdkVersion 20
+ buildToolsVersion "20.0.0"
+
+ defaultConfig {
+ applicationId "com.mycompany.myapplication"
+ minSdkVersion 13
+ targetSdkVersion 20
+ versionCode 1
+ versionName "1.0"
+ }
+
+ buildTypes {
+ release {
+ minifyEnabled false
+ proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+ }
+ debug {
+ debuggable true
+ }
+ }
+}
+
+dependencies {
+ compile fileTree(dir: 'libs', include: ['*.jar'])
+ compile 'com.android.support:appcompat-v7:20.0.0'
+ compile project(path: ':app2, configuration: 'android-endpoints')
+}
+</pre>
+
+
+<p class="note"><strong>Note:</strong> You can inject custom build logic for property values defined
+by a function that gets called by the property, for example:
+<pre>
+def computeVersionName() {
+ ...
+}
+
+android {
+ defaultConfig {
+ versionName computeVersionName()
+ ...
+ }
+}
+</pre>
+</p>
+
+
+
+<h2 id="dependencies">Dependencies</h2>
+
+<p>The Android Studio build system manages project dependencies and supports module dependencies,
+local binary dependencies, and remote binary dependencies.</p>
+
+<dl>
+ <dt><em>Module Dependencies</em></dt>
+ <dd><p>An application module can include in its build file a list of other modules it depends on.
+ When you build this module, the build system assembles and includes the required
+ modules.</p></dd>
+ <dt><em>Local Dependencies</em></dt>
+ <dd><p>If you have binary archives in your local filesystem that a module depends on, such as
+ JAR files, you can declare these dependencies in the build file for that module.</p></dd>
+ <dt><em>Remote Dependencies</em></dt>
+ <dd><p>When some of your dependencies are available in a remote repository, you do not have
+ to download them and copy them into your project. The Android Studio build system supports
+ remote dependencies from repositories, such as <a href="http://maven.apache.org/">Maven</a>,
+ and dependency managers, such as <a href="http://ant.apache.org/ivy/">Ivy</a>. </p>
+ <p>Many popular software libraries and tools are available in public Maven repositories.
+ For these dependencies you only have to specify their Maven coordinates, which uniquely
+ identify each element in a remote repository. The format for Maven coordinates used in the
+ build system is <code>group:name:version</code>. For example, the Maven coordinates for
+ version 16.0.1 of the Google Guava libraries are
+ <code>com.google.guava:guava:16.0.1</code>.</p>
+ <p>The <a href="http://search.maven.org">Maven Central Repository</a> is widely used to
+ distribute many libraries and tools.</p>
+ </dd>
+</dl>
+
+<h2 id="buildTasks">Build tasks</h2>
+
+<p>The Android Studio build system defines a hierarchical set of build tasks: the top-level or
+anchor tasks invoke dependent tasks to produce their collective build outcomes. The top-level build
+tasks are:</p>
+
+<dl>
+ <dt>assemble </dt>
+ <dd><p>Builds the project output. </p></dd>
+ <dt>check </dt>
+ <dd><p>Runs checks and tests.</p></dd>
+ <dt>build </dt>
+ <dd><p>Runs both assemble and check. </p></dd>
+ <dt>clean </dt>
+ <dd><p>Performs the clean.</p></dd>
+</dl>
+
+<p>The Android plugin provides additional tasks for <em>connectedCheck</em> and <em>deviceCheck</em>
+for checks run on connected, emulated, and remote devices. Gradle tasks can be viewed by clicking
+the Gradle tab</a> in the right margin.
+<img src="{@docRoot}images/tools/studio-gradle-tab.png"></p>
+<p class="img-caption"><strong>Figure 1:</strong> Gradle tab</p>
+
+<p>Running a top-level task, runs all the dependent tasks. For example, the <em>assemble</em> task
+has dependent tasks for <em>assembleDebug</em> and <em>assembleRelease</em> to make the debug and
+release APKs. The <em>assemble</em> task depends on these tasks so calling it builds both APKs.
+These tasks can also be called independently to build the debug or release APK separately. </p>
+
+<p>You can view the list of available tasks and invoke any task from Android Studio and from
+the command line, as described in
+<a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android Studio</a>
+and <a href="{@docRoot}tools/building/building-cmdline.html">Build the project from
+the command line</a>.</p>
+
+<h2 id="gradleWrapper">The Gradle wrapper</h2>
+
+<p>Android Studio projects contain the <em>Gradle wrapper</em>, which consists of:</p>
+
+<ul>
+ <li>A JAR file</li>
+ <li>A properties file</li>
+ <li>A shell script for Windows platforms</li>
+ <li>A shell script for Mac and Linux platforms</li>
+</ul>
+
+<p class="note"><strong>Note:</strong> You should submit all of these files to your source
+control system.</p>
+
+<p>Using the Gradle wrapper (instead of the local Gradle installation) ensures that
+you always run the version of Gradle defined in the <em>local.properties</em> file. To configure your
+project to use a newer version of Gradle, edit the properties file and specify the new version there.
+</p>
+
+<p>Android Studio reads the properties file from the Gradle wrapper directory inside your project
+and runs the wrapper from this directory, so you can seamlessly work with multiple projects
+that require different versions of Gradle.</p>
+
+<p class="note"><strong>Note:</strong> Android Studio does not use the shell scripts, so any
+changes you make to them won't work when building from the IDE. You should define your custom
+logic inside Gradle build files instead.</p>
+
+<p>You can run the shell scripts to build your project from the command line on your development
+machine and on other machines where Android Studio is not installed.</p>
+
+
+<h2 id="buildVariants"> Build variants</h2>
+
+<p>Each version of your app is represented in the build system by a <em>build variant</em>.
+Build variants are combinations of product flavors and build types. Product flavors represent
+product build versions of an app, such as free and paid. Build types represent the build
+packaging versions generated for each app package, such as debug and release. The build system
+generates APKs for each combination of product flavor and build type.</p>
+
+<p>By default, Android Studio defines default configuration settings, <code>defaultConfig</code> in
+the build.gradle file, and two build types (<em>debug</em> and <em>release</em>). This creates two
+build variants, debug and release, and the build system generates an
+APK for each variant. </p>
+
+<p>Adding two product flavors, <em>demo</em> and <em>full</em> along
+with the default build types <em>debug</em> and <em>release</em> generates four build variants,
+each with its own customized configuration:</p>
+
+<ul>
+ <li>demoDebug</li>
+ <li>demoRelease</li>
+ <li>fullDebug</li>
+ <li>fullRelease</li>
+</ul>
+
+Resources are merged across the multiple Android application sources:
+<ul>
+ <li>Build variants based on the buildType, and productFlavor build settings</li>
+ <li>The main sourceSet, generally located in src/main/res</li>
+ <li>Library Project dependencies, which contribute resources through the res entry in their aar
+ bundle.</li>
+</ul>
+
+<p>The priority of the merge order from lowest to highest is libraries/dependencies -> main src ->
+productFlavor -> buildType.</p>
+
+
+<p>Some projects have complex combinations of features along more than one dimension, but they
+still represent the same app. For example, in addition to having a demo and a full version of the
+app, some games may contain binaries specific to a particular CPU/ABI. The flexibility of
+the build system makes it possible to generate the following build variants for such a project:</p>
+
+<ul>
+ <li>x86-demoDebug</li>
+ <li>x86-demoRelease</li>
+ <li>x86-fullDebug</li>
+ <li>x86-fullRelease</li>
+ <li>arm-demoDebug</li>
+ <li>arm-demoRelease</li>
+ <li>arm-fullDebug</li>
+ <li>arm-fullRelease</li>
+ <li>mips-demoDebug</li>
+ <li>mips-demoRelease</li>
+ <li>mips-fullDebug</li>
+ <li>mips-fullRelease</li>
+</ul>
+
+<p>This project would consist of two build types (<em>debug</em> and <em>release</em>)
+and two <em>dimensions</em> of product flavors, one for app type (demo or full) and one for
+CPU/ABI (x86, ARM, or MIPS). </p>
+
+
+<h3>Source directories</h3>
+
+<p>To build each version of your app, the build system combines source code and
+resources from:</p>
+
+<ul>
+ <li><code>src/main/</code> - the main source directory (the default configuration common to all
+ variants)</li>
+ <li><code>src/<buildType>/</code> - the <buildType> source directory</li>
+ <li><code>src/<productFlavor>/</code> - the <productFlavor> source directory</li>
+</ul>
+
+<p class="note"><strong>Note:</strong> The build type and product flavor source directories are optional,
+as Android Studio does not create these directories for you. You should create these directories
+as you add build types and product flavors to the build configuration files. The build system does not
+use these directories if they are not present.</p>
+
+<p>For projects that do not define any flavors, the build system uses the <em>defaultConfig</em>
+settings, the main app directory and the default build type directories. For example, to generate
+the default <em>debug</em> and <em>release</em> build variants in projects with no product flavors,
+the build system uses:</p>
+<ul>
+ <li><code>src/main/</code> (default configuration)</li>
+ <li><code>src/release/</code> (build type)</li>
+ <li><code>src/debug/</code> (build type)</li>
+</ul>
+
+<p>For projects that define a set of product flavors, the build system merges the build type, product
+flavor and main source directories. For example, to generate the <em>full-debug</em> build variant,
+the build system merges the build type, product flavor and main directories:</p>
+<ul>
+ <li><code>src/main/</code> (default configuration)</li>
+ <li><code>src/debug/</code> (build type)</li>
+ <li><code>src/full/</code> (flavor)</li>
+</ul>
+
+<p>For projects that use flavor dimensions, the build system merges one flavor source directory per
+dimension. For example, to generate the <em>arm-demo-release</em> build variant, the build system
+merges:</p>
+<ul>
+ <li><code>src/main/</code> (default configuration)</li>
+ <li><code>src/release/</code> (build type)</li>
+ <li><code>src/demo/</code> (flavor - app type dimension)</li>
+ <li><code>src/arm/</code> (flavor - ABI dimension)</li>
+</ul>
+
+
+<p>The source code from these directories is used together to generate the output for a build
+variant. You can have classes with the same name in different directories as long as those
+directories are not used together in the same variant. </p>
+
+<p>The build system also merges all the manifests into a single manifest, so each build variant
+can define different components or permissions in the final manifest. The manifest merge priority
+from lowest to highest is libraries/dependencies -> main src -> productFlavor -> buildType. </p>
+
+<p>The build system merges all the resources from the all the source directories. If different
+folders contain resources with the same name for a build variant, the priority order is the
+following: build type resources override those from the product flavor, which override the
+resources in the main source directory, which override those in any libraries.</p>
+
+<p class="note"><strong>Note:</strong> Build variants enable you to reuse common activities,
+application logic, and resources across different versions of your app.</p>
+
+
diff --git a/docs/html/tools/publishing/app-signing.jd b/docs/html/tools/publishing/app-signing.jd
index 04e12cc..6e64392 100644
--- a/docs/html/tools/publishing/app-signing.jd
+++ b/docs/html/tools/publishing/app-signing.jd
@@ -81,10 +81,56 @@
set of private keys. You must keep your keystore in a safe and secure place.</li>
<li><em>Create a private key.</em> A <strong>private key</strong> represents the entity to
be identified with the app, such as a person or a company.</li>
-<li><em>Build your project</em>. Generate an unsigned APK for your app.</li>
-<li><em>Sign your app.</em> Use your private key to generate a signed version of your APK.</li>
+<li><p>Add the signing configuration to the build file for the <code>app</code> module:</p>
+ <p><pre>
+...
+android {
+ ...
+ defaultConfig { ... }
+ signingConfigs {
+ release {
+ storeFile file("myreleasekey.keystore")
+ storePassword "password"
+ keyAlias "MyReleaseKey"
+ keyPassword "password"
+ }
+ }
+ buildTypes {
+ release {
+ ...
+ signingConfig signingConfigs.release
+ }
+ }
+}
+...
+</pre></p>
+ </li>
+<li>Invoke the <code>assembleRelease</code> build task from Android Studio.</li>
</ol>
+<p>The package in <code>app/build/apk/app-release.apk</code> is now signed with your release key.</p>
+
+<p class="note"><strong>Note:</strong> Including the passwords for your release key and keystore
+inside the build file is not a good security practice. Alternatively, you can configure the build
+file to obtain these passwords from environment variables or have the build process prompt you
+for these passwords.</p>
+
+<p>To obtain these passwords from environment variables:</p>
+
+<pre>
+storePassword System.getenv("KSTOREPWD")
+keyPassword System.getenv("KEYPWD")
+</pre>
+
+<p>To have the build process prompt you for these passwords if you are invoking the build from
+the command line:</p>
+
+<pre>
+storePassword System.console().readLine("\nKeystore password: ")
+keyPassword System.console().readLine("\nKey password: ")
+</pre>
+
+
<p>After you complete this process, you can distribute your app and publish it on Google Play.</p>
<p class="warning"><strong>Warning:</strong> Keep your keystore and private key in a safe and
diff --git a/docs/html/tools/publishing/publishing_overview.jd b/docs/html/tools/publishing/publishing_overview.jd
index 3c56402..e42b2fb 100644
--- a/docs/html/tools/publishing/publishing_overview.jd
+++ b/docs/html/tools/publishing/publishing_overview.jd
@@ -73,7 +73,8 @@
<li>Building and signing a release version of your application.
<p>You can use the Gradle build files with the <em>release</em> build type to build and sign a
release version of your application. See
- <a href="{@docRoot}tools/gradle/studio-build.html">Building Your Project with Gradle</a>.</p>
+ <a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android
+ Studio</a>.</p>
</li>
<li>Testing the release version of your application.
<p>Before you distribute your application, you should thoroughly test the release version on at
@@ -109,7 +110,7 @@
<p>You can release your Android applications several ways. Usually, you release applications
through an application marketplace such as Google Play, but you can also release applications
-on your own website or by sending an application directly to a user.
+on your own website or by sending an application directly to a user.
<h3 id="publishing-marketplace">Releasing through an App Marketplace</h3>
@@ -183,7 +184,7 @@
<p class="note"><strong>Note:</strong> The <strong>Install Now</strong> button
shown in Figure 1 appears only if a user has configured their device to allow
-installation from <a href="#unknown-sources">unknown sources</a> and has opened your
+installation from <a href="#unknown-sources">unknown sources</a> and has opened your
email with the native Gmail application.</p>
<p>Distributing applications through email is convenient if you are sending your application to
@@ -223,9 +224,9 @@
apps from unknown sources." style="width:240px;" />
<p class="img-caption">
<strong>Figure 2.</strong> Users must enable the <strong>Unknown sources</strong>
- setting before they can install apps not downloaded from Google Play.
+ setting before they can install apps not downloaded from Google Play.
</p>
-</div>
+</div>
<p>Android protects users from inadvertent download and install of apps from
locations other than Google Play (which is trusted). It blocks such installs
@@ -234,7 +235,7 @@
the installation of applications from other sources, users need to enable the
Unknown sources setting on their devices, and they need to make this
configuration change <em>before</em> they download your application to their
-devices.</p>
+devices.</p>
<p class="note">Note that some network providers do not allow users to install
applications from unknown sources.</p>
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs
index 68e25cd..f23a26f 100644
--- a/docs/html/tools/tools_toc.cs
+++ b/docs/html/tools/tools_toc.cs
@@ -65,12 +65,10 @@
<span class="en">Building and Running</span></a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>tools/building/building-eclipse.html">
- <span class="en">From Eclipse with ADT</span></a></li>
+ <li><a href="<?cs var:toroot ?>tools/building/building-studio.html">
+ <span class="en">From Android Studio</span></a></li>
<li><a href="<?cs var:toroot ?>tools/building/building-cmdline.html">
<span class="en">From the Command Line</span></a></li>
- <li><a href="<?cs var:toroot ?>tools/building/multidex.html">
- <span class="en">Apps Over 65K Methods</span></a></li>
</ul>
</li>
@@ -226,13 +224,15 @@
<li class="nav-section">
<div class="nav-section-header">
- <a href="<?cs var:toroot ?>tools/gradle/index.html">Build System</a>
+ <a href="<?cs var:toroot ?>sdk/installing/studio-build.html">Build System</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>tools/gradle/studio-build.html">
- Building Your Project with Gradle</a></li>
- <li><a href="<?cs var:toroot ?>tools/gradle/gradle-ref.html">
- Gradle for Android Reference</a></li>
+ <li><a href="<?cs var:toroot ?>tools/building/configuring-gradle.html">
+ <span class="en">Configuring Gradle Builds</span></a></li>
+ <li><a href="<?cs var:toroot ?>tools/building/plugin-for-gradle.html">
+ <span class="en">Android Plugin for Gradle</span></a></li>
+ <li><a href="<?cs var:toroot ?>tools/building/multidex.html">
+ <span class="en">Apps Over 65K Methods</span></a></li>
</ul>
</li><!-- end of build system -->
@@ -300,6 +300,7 @@
<li><a href="<?cs var:toroot ?>tools/sdk/installing/migrate.html">Migrating to Android Studio</a></li>
<li><a href="<?cs var:toroot ?>tools/projects/projects-eclipse.html">Managing Projects</a></li>
<li><a href="<?cs var:toroot ?>tools/building/building-eclipse.html">Building and Running</a></li>
+ <li><a href="<?cs var:toroot ?>tools/building/building-cmdline-ant.html">Building with Ant</a></li>
<li><a href="<?cs var:toroot ?>tools/testing/testing_eclipse.html">Testing</a></li>
<li><a href="<?cs var:toroot ?>tools/debugging/debugging-projects.html">Debugging</a></li>
<li><a href="<?cs var:toroot ?>tools/publishing/app-signing-eclipse.html">Signing Your Apps</a></li>
