diff options
Diffstat (limited to 'docs/html/tools/building/building-cmdline.jd')
| -rw-r--r-- | docs/html/tools/building/building-cmdline.jd | 256 |
1 files changed, 123 insertions, 133 deletions
diff --git a/docs/html/tools/building/building-cmdline.jd b/docs/html/tools/building/building-cmdline.jd index b65fc78..c1a0dd2 100644 --- a/docs/html/tools/building/building-cmdline.jd +++ b/docs/html/tools/building/building-cmdline.jd @@ -18,32 +18,37 @@ 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 — <em>debug mode</em> — and one for building your - final package for release — <em>release mode</em>. Regardless of which way you build your application, - it must be signed before it can install on an emulator or device—with a debug key when building - in debug mode and with your own private key when building in release mode.</p> - - <p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile - and build your project. This will create the .apk file that you can install on an emulator or device. - When you build in debug mode, the .apk file is automatically signed by the SDK tools with - a debug key, so it's instantly ready for installation onto an emulator or attached + <p>By default, there are two build types to build your application using the gradle.build settings: + one for debugging your application — <em>debug</em> — and one for building your + final package for release — <em>release mode</em>. Regardless of which way you build type + your modules use, the app must be signed before it can install on an emulator or device—with + a debug key when building in debug mode and with your own private key when building in release mode.</p> + + <p>Whether you're building 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><your_module_name>-debug.apk</code>. The file is already signed + with the debug key and has been aligned with + <a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>. </p> + + <p>On Windows platforms, type this command:</p> + +<pre> +> gradlew.bat assembleDebug </pre> - <p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named - <code><your_project_name>-debug.apk</code>. The file is already signed with - the debug key and has been aligned with - <a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>. - </p> - </li> - </ol> +<p>On Mac OS and Linux platforms, type these commands:</p> - <p>Each time you change a source file or resource, you must run Ant again in order to package up +<pre> +$ chmod +x gradlew +$ ./gradlew assembleDebug +</pre> + + <p>The first command (<code>chmod</code>) adds the execution permission to the Gradle wrapper + script and is only necessary the first time you build this project from the command line.</p> + + <p>After you build the project, the output APK for the app module is located in + <code>app/build/outputs/apk/</code>, and the output AAR for any lib modules is located in + <code>lib/build/outputs/libs/</code>.</p> + + <p>To see a list of all available build tasks for your project, type this command:</p> + +<pre> +$ ./gradlew tasks +</pre> + + <p>Each time you change a source file or resource, you must run Gradle again in order to package up the latest version of the application.</p> - <p>To install and run your application on an emulator, see the following section about <a href= - "#RunningOnEmulator">Running on the Emulator</a>.</p> + <p>To install and run your application on an emulator, see the section about <a href= + "{@docRoot}tools/building/building-studio.html">Running on the Emulator</a>.</p> <h2 id="ReleaseMode">Building in Release Mode</h2> @@ -112,20 +135,24 @@ 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><your_project_name></em>-unsigned.apk</code>.</p> + directory, named <code><em><your_module_name></em>-unsigned.apk</code>.</p> <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't be installed until signed with your private key.</p> @@ -142,34 +169,47 @@ 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> - - <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}. + 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>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>Use Ant to compile your project in release mode: - <pre> -ant release -</pre> + <li>Open a command-line and navigate to the root of your module directory.</li> + + <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><your_project_name></em>-release.apk</code>. This .apk file has - been signed with the private key specified in {@code ant.properties} and aligned with {@code + <p>This creates your Android application .apk file inside the module <code>build/</code> + directory, named <code><em><your_module_name></em>-release.apk</code>. This .apk file has + been signed with the private key specified in gradle.build file and aligned with {@code zipalign}. It's ready for installation and distribution.</p> <h3 id="OnceBuilt">Once built and signed in release mode</h3> @@ -222,7 +262,7 @@ android avd adb install <em><path_to_your_bin></em>.apk </pre> - <p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/} + <p>Your .apk file (signed with either a release or debug key) is in your module {@code build/} directory after you build your application.</p> <p>If there is more than one emulator running, you must specify the emulator upon which to @@ -307,75 +347,25 @@ 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> - - <h2 id="AntReference">Ant Command Reference</h2> - <dt><code>ant clean</code></dt> - <dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code> -(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a -test project, the tested project is also cleaned.</dd> - - <dt><code>ant debug</code></dt> - <dd>Builds a debug package. Works on application, library, and test projects and compiles - dependencies as needed.</dd> - - <dt id="emma"><code>ant emma debug</code></dt> - <dd>Builds a test project while building the tested project with instrumentation turned on. - This is used to run tests with code coverage enabled.</dd> - - <dt><code>ant release</code></dt> - <dd>Builds a release package.</dd> - - <dt><code>ant instrument</code> - </dt> - <dd>Builds an instrumented debug package. This is generally called automatically when building a - test project with code coverage enabled (with the <code>emma</code> - target)</dd> - - <dt><code>ant <build_target> install</code></dt> - <dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd> - - <dt><code>ant installd</code></dt> - <dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not - already built.</dd> - - <dt><code>ant installr</code></dt> - <dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not - already built.</dd> - - <dt><code>ant installt</code></dt> - <dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the - tested application. This fails if the <code>.apk</code> is not already built.</dd> - - <dt><code>ant installi</code></dt> - <dd>Installs an already compiled instrumented package. This is generally not used manually as - it's called when installing a test package. This fails if the <code>.apk</code> is not already - built.</dd> - - <dt><code>ant test</code></dt> - <dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be - previously installed.</dd> - - <dt><code>ant debug installt test</code></dt> - <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and - runs the tests.</dd> - - <dt><code>ant emma debug install test</code></dt> - <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and - runs the tests with code coverage enabled.</dd> + means to you as an Android application developer. The document also includes a guide to publishing + and signing your application.</p> + + <h2 id="Grad;eReference">Gradle Build Language Reference</h2> + +<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> |