Android Shell Tool Guide

Android Shell Tool Guide

This guide shows how to use Cordova's set of platform-centered shell tools to develop Android apps. This development path, discussed in the Overview, may offer you a greater range of development options than the cross-platform CLI tool described in The Command-Line Interface. For example, you need to use shell tools when deploying a custom Cordova WebView alongside native components. Before using either development path, you must first configure the Android SDK environment as described in the Android Platform Guide.

To enable shell tools for Android, download Cordova from cordova.apache.org. The download contains separate archives for each platform. Expand each you wish to target, android in this case. The relevant tools are typically available in the top-level bin directory, otherwise consult the README file for more detailed directions.

These tools allow you to create, build, and run Android apps. For information on the additional command-line interface that enables plugin features across all platforms, see Using Plugman to Manage Plugins. See Application Plugins for details on how to develop plugins.

Create a Project

Run the create command, specifying the existing path to the project, the reverse-domain-style package identifier, and the app's display name. Here is the syntax for both Mac/Linux and Windows:

    $ /path/to/cordova-android/bin/create /path/to/project com.example.project_name ProjectName

    C:\>\path\to\cordova-android\bin\create.bat \path\to\project com.example.project_name ProjectName

Build

This cleans then builds a project.

Debug, on Mac/Linux or Windows:

    $ /path/to/project/cordova/build --debug

    C:\>\path\to\project\cordova\build.bat --debug

Release, on Mac/Linux or Windows:

    $ /path/to/project/cordova/build --release

    C:\>\path\to\project\cordova\build.bat --release

Run the App

The run command accepts the following optional parameters:

Make sure you create at least one Android Virtual Device, otherwise you're prompted to do so with the android command. If more than one AVD is available as a target, you're prompted to select one. By default the run command detects a connected device, or a currently running emulator if no device is found.

Signing the App

You can review Android app signing requirements here: http://developer.android.com/tools/publishing/app-signing.html

To sign an app, you need the following parameters:

Alternatively, you could specify them in a build configuration file (build.json) using (--buildConfig) argument. Here's a sample of a build configuration file:

{
     "android": {
         "debug": {
             "keystore": "..\android.keystore",
             "storePassword": "android",
             "alias": "mykey1",
             "password" : "password",
             "keystoreType": ""
         },
         "release": {
             "keystore": "..\android.keystore",
             "storePassword": "",
             "alias": "mykey2",
             "password" : "password",
             "keystoreType": ""
         }
     }
 }

For release signing, passwords can be excluded and the build system will issue a prompt asking for the password.

There is also support to mix and match command line arguments and parameters in build.json file. Values from the command line arguments will get precedence. This can be useful for specifying passwords on the command line.

Logging

    $ /path/to/project/cordova/log

    C:\>\path\to\project\cordova\log.bat

Cleaning

    $ /path/to/project/cordova/clean

    C:\>\path\to\project\cordova\clean.bat

Building with Gradle

As of [email protected], project build using Gradle. For instructions on building with ANT, refer to older versions of documentation.

Gradle Properties

These properties can be set to customize the build:

Extending build.gradle

If you need to customize build.gradle, rather than edit directly, you should create a sibling file named build-extras.gradle. This file will be included by the main build.gradle when present. Here's an example:

# Example build-extras.gradle
# This file is included at the beginning of `build.gradle`
ext.cdvDebugSigningPropertiesFile = '../../android-debug-keys.properties'
# When set, this function allows code to run at the end of `build.gradle`
ext.postBuildExtras = {
    android.buildTypes.debug.applicationIdSuffix = '.debug'
}

Note that plugins can also include build-extras.gradle files via:

<framework src="some.gradle" custom="true" type="gradleReference" />

Example Build

export ORG_GRADLE_PROJECT_cdvMinSdkVersion=14
cordova build android -- --gradleArg=-PcdvBuildMultipleApks=true