Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs:build system updates [CP]

Browse Source 
Cherry-pick from Change-Id: I8a5810824cbef3bb81173d80827075d3754d7573

Change-Id: I1e948a18a5e7cc58ae712c50887e69ab8600e536
This commit is contained in:
Rich Slogar
2014-11-06 17:15:28 -08:00
committed by Joe Fernandez
parent d0c79c4e95
commit 4083327e0e
15 changed files with 1835 additions and 1252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/html/images/tools/buildfilebasics_appbuildfile.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/html/images/tools/studio-gradle-tab.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/html/images/tools/studio-main-screen.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 161 KiB

BIN
docs/html/images/tools/studio-module-build-file.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/html/images/tools/studio-project-build-file.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

1082
docs/html/sdk/installing/studio-build.jd
View File

File diff suppressed because it is too large Load Diff

381
docs/html/tools/building/building-cmdline-ant.jd Normal file
View File

@@ -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 &mdash; <em>debug mode</em> &mdash; and one for building your
final package for release &mdash; <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&mdash;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\&lt;jdkdir&gt;</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>&lt;your_project_name&gt;-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>&lt;your_project_name&gt;</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>&lt;your_project_name&gt;</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 &gt; Applications &gt; 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>&lt;path_to_your_bin&gt;</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 &lt;build_target&gt; 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>

246
docs/html/tools/building/building-cmdline.jd
View File

@@ -18,32 +18,37 @@ parent.link=index.html
<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 &mdash; <em>debug mode</em> &mdash; and one for building your
final package for release &mdash; <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&mdash;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 &mdash; <em>debug</em> &mdash; and one for building your
final package for release &mdash; <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&mdash;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 @@ Emulator</a></li>
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 @@ Emulator</a></li>
<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 @@ Emulator</a></li>
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>&lt;your_module_name&gt;-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>&lt;your_project_name&gt;-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 @@ ant debug
<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>&lt;your_project_name&gt;</em>-unsigned.apk</code>.</p>
directory, named <code><em>&lt;your_module_name&gt;</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 @@ ant release
<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 @@ ant release
</li>
</ol>
<p>This creates your Android application .apk file inside the project <code>bin/</code>
directory, named <code><em>&lt;your_project_name&gt;</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>&lt;your_module_name&gt;</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 @@ android avd
adb install <em>&lt;path_to_your_bin&gt;</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 @@ adb -d install <em>path/to/your/app</em>.apk
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 &lt;build_target&gt; 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>

256
docs/html/tools/building/building-studio.jd Normal file
View File

@@ -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-&lt;flavor>-&lt;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&mdash;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> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <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> &gt; <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>&lt;application&gt;</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> &gt; <strong>Run</strong> (or <strong>Run</strong> &gt;
<strong>Debug</strong>) from the Android Studio menu bar.</p>

478
docs/html/tools/building/configuring-gradle.jd Normal file
View File

@@ -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>&lt;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>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;resources>
&lt;string name="hello_world">Demo version only.&lt;/string>
&lt;/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>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;resources>
&lt;string name="hello_world">This is the full version!&lt;/string>
&lt;/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>
&lt;LinearLayout ...>
...
&lt;Button
android:id="@+id/button2"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/button2"
android:onClick="onButton2Clicked"/>
&lt;/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>
&lt;manifest ...>
&lt;application ...>
...
&lt;activity
android:name="com.buildsystemexample.app.SecondActivity"
android:label="@string/title_activity_second" >
&lt;/activity>
&lt;/application>
&lt;/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>

114
docs/html/tools/building/index.jd
View File

@@ -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>
<img src="{@docRoot}images/build-simplified.png" />

448
docs/html/tools/building/plugin-for-gradle.jd Normal file
View File

@@ -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/&lt;buildType>/</code> - the <buildType> source directory</li>
<li><code>src/&lt;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>

50
docs/html/tools/publishing/app-signing.jd
View File

@@ -81,10 +81,56 @@ The debug build type is set to use this debug <code>SigningConfig</code> automat
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

13
docs/html/tools/publishing/publishing_overview.jd
View File

@@ -73,7 +73,8 @@ tasks:</p>
<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 @@ application.</p>
<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 @@ button.</p>
<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 @@ help prevent unauthorized installation and use of your application.</p>
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 @@ Settings&nbsp;<strong>&gt;</strong>&nbsp;Security, shown in Figure 2. To allow
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>

19
docs/html/tools/tools_toc.cs
View File

@@ -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 @@ class="en">MonkeyRunner</span></a></li>
<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 @@ class="en">Support Library</span></a></div>
<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>