cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rakatyal <>
Subject [GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements
Date Wed, 03 Feb 2016 22:53:59 GMT
Github user rakatyal commented on a diff in the pull request:
    --- Diff: www/docs/en/dev/guide/platforms/android/ ---
    @@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see
     ## Requirements and Support
    +### Java Development Kit (JDK)
    +Install [Java Development Kit (JDK) 7](
    +or later.
    +When installing on Windows you also need to set `JAVA_HOME` Environment Variable
    +according to JDK installation path (for example, `C:\Program Files\Java\jdk1.7.0_75`).
    +### Android SDK
     Cordova for Android requires the Android SDK which could be installed
     on OS X, Linux or Windows operation system. See the Android SDK's
     [System Requirements](
    -Cordova supports Android 4.0.x (starting with Android API level 14)
    -and higher.  As a general rule, Android versions become unsupported by Cordova as
    +Cordova's latest Android package supports up to Android [API-Level](
    +The supported Android API-Levels for the past few cordova-android releases can
    +be found in this table:
    +cordova-android Version | Supported Android API-Levels
    +5.X.X                   | 14 - 23
    +4.1.X                   | 14 - 22
    +4.0.X                   | 10 - 22
    +3.7.X                   | 10 - 21
    +Please note that the versions listed here are for Cordova's Android package,
    +[cordova-android](, and not for the
    +Cordova CLI. To determine what version of Cordova's Android package is installed
    +in your Cordova project, run the command `cordova platform ls` in the directory
    +that holds your project.
    +As a general rule, Android versions become unsupported by Cordova as
     they dip below 5% on Google's
     [distribution dashboard](
    -Android versions earlier than API level 10, and the 3.x versions (Honeycomb,
    -API levels 11-13) fall significantly below that 5% threshold.
    -## Install Cordova Shell Tools
    -If you want to use Cordova's Android-centered shell tools in
    -conjunction with the SDK, download Cordova from
    -[]( Otherwise ignore this
    -section if you plan to use the cross-platform CLI tool described in
    -[The Command-Line Interface](../../cli/index.html).
    -The Cordova download contains separate archives for each platform. Be
    -sure to expand the appropriate archive, `android` in this case, within
    -an empty directory.  The relevant executible utilities are available
    -in the top-level `bin` directory. (Consult the __README__ file if
    -necessary for more detailed directions.)
    +#### Installing the Android SDK
    -These shell 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
    -## Install the Java Development Kit (JDK)
    -Install [Java Development Kit (JDK) 7](
    -or later. 
    -When installing on Windows you also need to set `JAVA_HOME` Environment Variable
    -according to JDK installation path (for example, C:\Program Files\Java\jdk1.7.0_75).
    -## Install the Android SDK
    -Install the [Android Stand-alone SDK Tools](
or [Android Studio]( Procceed
with `Android Studio` if you plan 
    +Install the [Android Stand-alone SDK Tools](
or [Android Studio](
    +Proceed with Android Studio if you plan on
     developing new Cordova for Android plugins or using native tools to
    -run and debug Android platform. Otherwise, `Android Stand-alone SDK Tools`
    -are enough to build and deploy Android application.
    +run and debug the Android platform. Otherwise, the Android Stand-alone SDK Tools
    +are enough to build and deploy Android applications.
     Detailed installation instructions are available as part of installation
     links above.
    -For Cordova command-line tools to work, or the CLI that is based upon
    -them, you need to include the SDK's `tools` and `platform-tools`
    -directories in your `PATH`.  On a Mac or Linux, you can use a text editor to
    -create or modify the `~/.bash_profile` file, adding a line such as the
    -following, depending on where the SDK installs:
    +#### Update your PATH
    +For Cordova's CLI and command line tools to work correctly, you will need to
    +include the SDK's `tools` and `platform-tools` directories in your `PATH`.
    +##### OS X and Linux
    +On a Mac or Linux, you can use a text editor to create or modify the
    +`~/.bash_profile` file, adding a line such as the following
    +(substitute the paths with your local Android SDK installation's location):
             export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools
    -This line in `~/.bash_profile` exposes these tools in newly opened terminal
    -windows. If your terminal window is already open in OSX, or to avoid a logout/login
    -on Linux, run this to make them available in the current terminal window:
    +Reload your terminal to see this change reflected or run the following command:
             $ source ~/.bash_profile
    -To modify the `PATH` environment on Windows:
    +##### Windows
    +On Windows, you must modify the `PATH` environment variable. These steps may
    +vary depending on your installed version of Windows:
    -1. Click on the __Start__ menu in the lower-left corner of the desktop,
    -   right-click on __Computer__, then select __Properties__.
    +1. Click on the __Start__ menu in the lower-left corner of the desktop
    -1. Select __Advanced System Settings__ in the column on the left.
    +1. In the search bar, search for __Environment Variables__ and select __Edit the system
Environment Variables__ from the options that appear
    -1. In the resulting dialog box, press __Environment Variables__.
    +1. In the window that appears, click the __Environment Variables__ button
     1. Select the __PATH__ variable and press __Edit__.
    -1. Append the following to the `PATH` based on where you installed the
    -   SDK, for example:
    +1. Append the relevant locations to the __PATH__ based on where you installed
    +   the SDK, for example:
     1. Save the value and close both dialog boxes.
    -## Install SDK Packages
    -Open Android SDK Manager (for example, via terminal: `android`) and install:
    -1. Android 5.1.1 (API 22) platform SDK
    -1. Android SDK Build-tools version 19.1.0 or higher
    -1. Android Support Repository (Extras)
    -See [Installing SDK Packages](
    -for more details.
    -## Configure an Emulator
    -Android sdk doesn't provide any default emulator instance by default. You can 
    -create a new one by running `android` on the command line.
    -The press __Tools &rarr; Manage AVDs__ (Android Virtual Devices),
    -then choose any item from __Device Definitions__ in the resulting dialog
    -![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_device.png)
    -Press __Create AVD__, optionally modifying the name, then press __OK__
    -to accept the changes:
    -![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_newAVD.png)
    -The AVD then appears in the __Android Virtual Devices__ list:
    -![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_avds.png)
    -To open the emulator as a separate application, select the AVD and
    -press __Start__. It launches much as it would on the device, with
    -additional controls available for hardware buttons:
    -![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_emulator.png)
    +1. Close and reopen any command prompt windows to see the change reflected
    -For a faster experience, you can use the `Virtual Machine Acceleration` to improve 
    -the execution speed.
    -Many modern CPUs provide extensions to execute Virtual Machines more efficiently.
    -Before attempting to use this type of acceleration, you need to determine if your 
    -current development system's CPU, supports one the following virtualization technologies:
    +#### Adding SDK Packages
    -* __Intel Virtualization Technology__ (VT-x, vmx) &rarr; [Intel VT-x supported processor
    -* __AMD Virtualization__ (AMD-V, SVM), only supported for Linux (Since May 2006, all
CPUs AMD include AMD-V, except Sempron).
    +After installing the Android SDK, you must also install the packages for
    +whatever [API level](
    +you wish to target. It is recommended that you install the highest SDK version
    +that your version of cordova-android supports (see above).
    -Another way to find out if your Intel processor supports VT-x Technology, it's by executing
    -`Intel Processor Identification Utility`, for `Windows`you can download it from the Intel
[Download Center](,
    -or you can use the [booteable utility](,
which is `OS Independent`.
    +Open Android SDK Manager (for example, run `android` from the terminal) and make
    +sure the following are installed:
    -After install and execute the `Intel Processor Identification Utility` over Windows,
you will get the following window, 
    -in order to check if your CPU supports the Virtualization Technologies:
    -![]({{ site.baseurl }}/static/img/guide/platforms/android/intel_pid_util_620px.png)
    -In order to speed up the emulator, you need to download and install one or more `Intel
x86 Atom` System Images, 
    -as well as the `Intel Hardware Accelerated Execution Manager (HAXM)`.
    -Open your Android SDK Manager, and select the `Intel x86 Atom` System Image, for whichever
version that you want to test. Then go to `Extras` 
    -and select `Intel x86 Emulator Accelerator (HAXM)`, and install those packages:
    -![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_man_intel_image_haxm.png)
    -After download, run the Intel installer, which is available within your
    -Android SDK at `extras/intel/Hardware_Accelerated_Execution_Manager`. 
    -__Note__:`If you have any problems installing the package, you can find more information
and step by step guidance check this` 
    -[Intel Article](
    -1. Install one or more `Intel x86 Atom` System Images as well as the
    -   `Intel Hardware Accelerated Execution Manager`, available under
    -   __Extras__.
    -1. Run the Intel installer, which is available within your Android SDK
    -   at `extras/intel/Hardware_Accelerated_Execution_Manager`.
    -1. Create a new AVD with the target set to an Intel image.
    -1. When starting the emulator, ensure there are no error messages
    -   indicating a failure to load HAX modules.
    -## Create a New Project
    -At this point, to create a new project you can choose between the
    -cross-platform CLI tool described in [The Command-Line Interface](../../cli/index.html),
    -the set of Android-specific shell tools. From within a source-code
    -directory, here's the CLI approach:
    -        $ cordova create hello com.example.hello HelloWorld
    -        $ cd hello
    -        $ cordova platform add android
    -        $ ccordova prepare              # or "cordova build"
    -Here's the corresponding lower-level shell-tool approach for both Unix
    -and Windows:
    -        $ /path/to/cordova-android/bin/create /path/to/new/hello com.example.hello HelloWorld
    -        C:\path\to\cordova-android\bin\create.bat C:\path\to\new\hello com.example.hello
    -## Build the Project
    -If you are using the CLI in development, the project directory's
    -top-level `www` directory contains the source files. Run any of
    -these within the project directory to rebuild the app:
    -        $ cordova build                   # build all platforms that were added
    -        $ cordova build android           # build debug for only Android
    -        $ cordova build android --debug   # build debug for only Android
    -        $ cordova build android --release # build release for only Android
    -If you are using the Android-specific shell tools in development,
    -there is a different approach.  Once you generate the project, the
    -default app's source is available in the `assets/www` subdirectory.
    -Subsequent commands are available in its `cordova` subdirectory.
    -The `build` command cleans project files and rebuilds the app. Here is
    -the syntax for both Mac and Windows. The first pair of examples
    -generate debugging information, and the second builds the apps for
    -        $ /path/to/project/cordova/build --debug
    -        C:\path\to\project\cordova\build.bat --debug
    -        $ /path/to/project/cordova/build --release
    -        C:\path\to\project\cordova\build.bat --release
    -## Deploy the app
    -You can use the `cordova` CLI utility to deploy the
    -application to the emulator or the device from the command line:
    -        $ cordova emulate android       #to deploy the app on a default android emulator
    -        $ cordova run android --device  #to deploy the app on a connected device
    -Otherwise, use the alternate shell interface:
    -        $ /path/to/project/cordova/run --emulator
    -        $ /path/to/project/cordova/run --device
    -You can use __cordova run android --list__ to see all available targets and 
    -__cordova run android --target=target_name__ to run application on a specific 
    -device or emulator (for example,  `cordova run android --target="Nexus4_emulator"`).
    -You can also use __cordova run --help__ to see additional build and run
    -This pushes the app to the home screen and launches it:
    +1. Android Platform SDK for your targeted version of Android
    +1. Android SDK Build-tools version 19.1.0 or higher
    +1. Android Support Repository (found under "Extras")
    -![]({{ site.baseurl }}/static/img/guide/platforms/android/emulator2x.png)
    +See Android's documentation on [Installing SDK Packages](
    +for more details.
    -When you `run` the app, you also `build` it. You can append additional
    -`--debug`, `--release`, and `--nobuild` flags to control how it is
    -built, or even whether a rebuild is necessary:
    +## Setting up an Emulator
    -        $ /path/to/project/cordova/run --emulator --nobuild
    +If you wish to run your Cordova app on an Android emulator, you will first need
    +to create an Android Virtual Device (AVD). See the Android documentation for
    +[managing AVDs](
    +and the [instructions](
    +for configuring the emulator and setting up hardware acceleration.
    -## Other Commands
    +Once your AVD is configured correctly, you should be able to see it by running
    +the command:
    -The following generates a detailed log of the app as it runs:
    +    $ cordova run --list
    -        $ /path/to/project/cordova/log
    -        C:\path\to\project\cordova\log.bat
    +## Opening a Project in Android Studio
    -The following cleans the project files:
    +Cordova for Android projects can be opened in the Android IDE, [Android Studio](
    +This can be useful if you wish to use Android Studio's built in Android
    +debugging/profiling tools or if you are developing Android plugins. Please note
    +that when opening your project in Android studio, it is recommended that you do
    +NOT edit your code in the IDE. This will edit the code in the `platforms` folder
    +of your project (not `www`), and changes are liable to be overwritten. Instead,
    +edit the `www` folder and copy over your changes by running `cordova build`.
    -        $ /path/to/project/cordova/clean
    -        C:\path\to\project\cordova\clean.bat
    +Plugin developers wishing to edit their native code in the IDE should use the
    +`--link` flag when adding their plugin to the project via `cordova plugin add`.
    +This will link the files so that changes to the plugin files in the `platforms`
    +folder are reflected in your plugin's source folder (and vice versa).
    -## Open a New Project in the SDK
    +To open a Cordova for Android project in Android Studio:
    -Once android platform is added to your project, you can open it from 
    -within [Android Studio](
    +  1. Launch __Android Studio__.
    -1. Launch the __Android Studio__ application.
    +  1. Select __Import Project (Eclipse ADT, Gradle, etc)__.
    -1. Select __Import Project (Eclipse ADT, Gradle, etc)__.
    +      ![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_import_project.png)
    -  ![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_import_project.png)
    +  1. Select the Android platform directory in your project (`<your-project>/platforms/android`).
    -1. Select location where android platform is stored (`your/project/platforms/android`).
    -  ![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_import_select_location.png)
    +      ![]({{ site.baseurl }}/static/img/guide/platforms/android/asdk_import_select_location.png)
    -1. For the `Gradle Sync` question you can simply answer __Yes__.
    +  1. For the `Gradle Sync` question you can simply answer __Yes__.
    -You are all set now and can build and run the app directly from `Android Studio`.
    +Once it finishes importing, you should be able build and run the app directly
    --- End diff --
    able to

If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at or file a JIRA ticket
with INFRA.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message