You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@cordova.apache.org by riknoll <gi...@git.apache.org> on 2016/01/28 19:07:20 UTC

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

GitHub user riknoll opened a pull request:

    https://github.com/apache/cordova-docs/pull/471

    CB-10332 Android Guide Improvements

    Lot's of changes, including:
    
    * Fixing Markdown, links, grammar, etc.
    * Removing outdated and duplicated content
    * Removing content where we should just point to the Android docs (like setting up an emulator)
    
    Things left to do:
    
    * Combine all the pages into one page
    * Completely rewrite the guide for embedding a webview (it is 100% outdated)
    * Remove pages that shouldn't exist anymore (Android's config.xml got integrated into the main doc)

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/riknoll/cordova-docs CB-10332

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/cordova-docs/pull/471.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #471
    
----
commit 67d21293f7e1d812cc5390d08bc602008e762b89
Author: riknoll <ri...@gmail.com>
Date:   2016-01-26T18:16:21Z

    CB-10332: Android guide improvements

commit c70b4246f46a81fec40466c6d8570c6089192acd
Author: riknoll <ri...@gmail.com>
Date:   2016-01-28T02:03:33Z

    CB-10332: Minor fixes to Android Guide

----


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-181506432
  
    I moved the lifecycle guide into the single page guide and added redirects to our `.htaccess` file that handle requests for all of the pages that got combined.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by nikhilkh <gi...@git.apache.org>.

Github user nikhilkh commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51832927
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -31,12 +31,12 @@ platform and back.  For another sample, see also the comments in
     [CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java).
     
     Android plugins are based on Cordova-Android, which consists of an
    -Android WebView with hooks attached to it.  Plugins are represented as
    -class mappings in the `config.xml` file.  A plugin consists of at
    +Android WebView with hooks attached to it. Plugins are represented as
    +class mappings in the `config.xml` file. A plugin consists of at
     least one Java class that extends the `CordovaPlugin` class,
    -overriding one of its `execute` methods. As best practice, the plugin
    -should also handle `[pause](../../../cordova/events/events.pause.html)` and `[resume](../../../cordova/events/events.resume.html)` events, along with any message
    -passing between plugins.  Plugins with long-running requests,
    +overriding one of its `execute` methods. As a best practice, the plugin
    +should also handle [`pause`](../../../cordova/events/events.pause.html) and [`resume`](../../../cordova/events/events.resume.html) events, along with any message
    --- End diff --
    
    Should you link to android lifecyle here?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51801334

--- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
@@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the

## Requirements and Support

+### Java Development Kit (JDK)
+
+Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
+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](http://developer.android.com/sdk/index.html#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](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) 23.
+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](https://github.com/apache/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](http://developer.android.com/about/dashboards/index.html).
-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
-[cordova.apache.org](http://cordova.apache.org). 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
-plugins.
-
-## Install the Java Development Kit (JDK)
-
-Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
-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](http://developer.android.com/sdk/installing/index.html?pkg=tools) or [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio). Procceed with `Android Studio` if you plan
+Install the [Android Stand-alone SDK Tools](http://developer.android.com/sdk/installing/index.html?pkg=tools) or [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio).
+Proceed with Android Studio if you plan on
developing new Cordova for Android plugins or using native tools to
--- End diff --

For some reason this article says "Cordova for Android" all over the place and so I kept that up. This sentence was referring to plugins. Android Studio can be used with apps, but I think the better use case is with plugins.

---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by nikhilkh <gi...@git.apache.org>.

Github user nikhilkh commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51833532
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -155,27 +158,24 @@ thread, but do not want to block the `WebCore` thread either:
     
     ## Adding Dependency Libraries
     
    -If a plugin requires additional libraries to work, you can use
    -one of the following approaches to add them via `config.xml`.
    +If your Android plugin has extra dependencies, they must be listed in the
    +`plugin.xml` in one of two ways.
     
    -Option A. Via _Gradle_ reference, for example:
    -
    -        <framework src="com.android.support:support-v4:+" />
    -
    -This is a recommended approach as it allows multiple plugins
    -to refer to the same dependency library such as _gson_,
    -_android-support-v4_, _google-play-services_, etc and
    -_Gradle_ will resolve duplicate dependencies using its
    +The preferred way is to use the `<framework />` tag (see the
    +[Plugin Specification](../../../plugin_ref/spec.html) for more details).
    +Specifying libraries in this manner allows them to be resolved via Gradle's
     [Dependency Management logic](https://docs.gradle.org/current/userguide/dependency_management.html).
    -
    -Option B. As _JAR_ files placed to some plugin's folder and
    -linked using `lib-file`, for example:
    -
    -        <lib-file src="src/android/libs/gcm.jar"/>
    -
    -We recommend using this approach only if you are sure that
    -dependency jar is plugin specific and won't be used by
    -other plugins. Otherwise, there will be platform build issue.
    +This allows commonly used libraries such as _gson_, _android-support-v4_,
    +and _google-play-services_ to be used by multiple plugins without conflict.
    +
    +The second option is to use the `<lib-file />` tag to specify the location of
    --- End diff --
    
    Does `framework` support a jar reference too? Are these mutually exclusive or `framework` is always preferred over `lib-file`?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-180608678
  
    Okay, I just forced pushed some major changes to this PR:
    
    * Addressed most of the code review
    * Deleted old pages and combined other pages into single page guide
    * Lots of miscellaneous content fixes and reorganization to fit the single page platform guide structure
    * Rebased to master
    
    Plugin guide is still separate, since that is going to move. Lifecycle is also separate, because I need to figure out what to do about that since I've been handing out links to that page all over the place because of the save-restore API changes.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r53357772
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -23,24 +23,17 @@ title: Android Plugins
     # Android Plugins
     
     This section provides details for how to implement native plugin code
    -on the Android platform. Before reading this, see Application Plugins
    +on the Android platform. Before reading this, see the [Plugin Development Guide][plugin-dev]
    --- End diff --
    
    I am okay with anything as long as it's consistent. 'Android Development Guide' and 'Android Plugin Development Guide' and so on for each platform?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by vladimir-kotikov <gi...@git.apache.org>.

Github user vladimir-kotikov commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51309545
  
    --- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
    @@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the
     
     ## Requirements and Support
     
    +### Java Development Kit (JDK)
    +
    +Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
    +or later.
    +
    +When installing on Windows you also need to set `JAVA_HOME` Environment Variable
    --- End diff --
    
    I'm not 100% sure, but this is someting that should be set by `check_reqs` at the [build time](https://github.com/apache/cordova-android/blob/master/bin/lib/check_reqs.js#L99)


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51801961

--- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
@@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the

## Requirements and Support

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:

;C:\Development\android-sdk\platform-tools;C:\Development\android-sdk\tools

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](http://developer.android.com/sdk/installing/adding-packages.html)
-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
-box:
-
-![]({{ 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 list](http://ark.intel.com/products/virtualizationtechnology)
-* __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](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)
+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 the
-`Intel Processor Identification Utility`, for `Windows`you can download it from the Intel [Download Center](https://downloadcenter.intel.com/Detail_Desc.aspx?ProductID=1881&DwnldID=7838),
-or you can use the [booteable utility](https://downloadcenter.intel.com/Detail_Desc.aspx?ProductID=1881&DwnldID=7840&lang=eng), 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](http://software.intel.com/en-us/android/articles/speeding-up-the-android-emulator-on-intel-architecture).
-
-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), or
-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 HelloWorld
-
-## 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
-release:
-
- $ /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
-options.
-
-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](http://developer.android.com/sdk/installing/adding-packages.html)
+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](http://developer.android.com/tools/devices/managing-avds.html)
+and the [instructions](http://developer.android.com/tools/devices/emulator.html)
+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](http://developer.android.com/sdk/installing/index.html?pkg=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](http://developer.android.com/sdk/installing/index.html?pkg=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

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by nikhilkh <gi...@git.apache.org>.

Github user nikhilkh commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51833065
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -72,7 +72,7 @@ Otherwise, the plugin may compile but still be unavailable to Cordova.
     One instance of a plugin object is created for the life of each
     `WebView`. Plugins are not instantiated until they are first
     referenced by a call from JavaScript, unless `<param>` with an `onload`
    -`name` attribute is set to `"true"` in `config.xml`. E.g.:
    +`name` attribute is set to `"true"` in `config.xml`. For example,
     
         <feature name="Echo">
             <param name="android-package" value="<full_name_including_namespace>" />
    --- End diff --
    
    What does the `android-package` stand for?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51802869

--- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
@@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the

## Requirements and Support

Detailed installation instructions are available as part of installation
links above.

export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools

$ 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. 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:

;C:\Development\android-sdk\platform-tools;C:\Development\android-sdk\tools

1. Save the value and close both dialog boxes.

-## 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
--- End diff --

Doesn't hurt, I guess.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-185451042
  
    @rakatyal I thought we were deleting the upgrading article


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by omefire <gi...@git.apache.org>.

Github user omefire commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r52791195
  
    --- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
    @@ -30,278 +30,676 @@ platform-centered shell tools or cross-platform Cordova CLI for
     development. For a comparison of the two development paths, see the
     [Overview](../../overview/index.html).  For details on the CLI, see [The Command-Line Interface](../../cli/index.html).
    --- End diff --
    
    Link should point to: http://localhost:3000/docs/en/dev/guide/overview/index.html#development-paths


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51800700
  
    --- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
    @@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the
     
     ## Requirements and Support
     
    +### Java Development Kit (JDK)
    +
    +Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
    +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](http://developer.android.com/sdk/index.html#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](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) 23.
    +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](https://github.com/apache/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](http://developer.android.com/about/dashboards/index.html).
    -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
    -[cordova.apache.org](http://cordova.apache.org). 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
    -plugins.
    -
    -## Install the Java Development Kit (JDK)
    -
    -Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
    -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](http://developer.android.com/sdk/installing/index.html?pkg=tools) or [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio). Procceed with `Android Studio` if you plan 
    +Install the [Android Stand-alone SDK Tools](http://developer.android.com/sdk/installing/index.html?pkg=tools) or [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio).
    +Proceed with Android Studio if you plan on
     developing new Cordova for Android plugins or using native tools to
    --- End diff --
    
    new Cordova apps or Android plugins?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-177044144
  
    @vladimir-kotikov Thanks for the heads up, I wasn't aware of that! After discussing this with @nikhilkh, I think I'm going to leave the instructions in but add that Cordova will try to do it automatically. Seems like that script might not always work.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51802258

--- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
@@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the

## Requirements and Support

Detailed installation instructions are available as part of installation
links above.

export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools

$ 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. 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:

;C:\Development\android-sdk\platform-tools;C:\Development\android-sdk\tools

1. Save the value and close both dialog boxes.

-## 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
--- End diff --

Can we list the expected output?

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by asfgit <gi...@git.apache.org>.

Github user asfgit closed the pull request at:

    https://github.com/apache/cordova-docs/pull/471


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by nikhilkh <gi...@git.apache.org>.

Github user nikhilkh commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-179666263
  
    Should we add a section on "Diagnosing failures" - it could be part of a subsequent PR - in particular, talking about adb logcat or referencing appropriate Android docs.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by omefire <gi...@git.apache.org>.

Github user omefire commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r53241742
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -23,24 +23,17 @@ title: Android Plugins
     # Android Plugins
     
     This section provides details for how to implement native plugin code
    -on the Android platform. Before reading this, see Application Plugins
    +on the Android platform. Before reading this, see the [Plugin Development Guide][plugin-dev]
    --- End diff --
    
    This section should probably be renamed: 'Android Plugin Development Guide'.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51802949
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -31,12 +31,12 @@ platform and back.  For another sample, see also the comments in
     [CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java).
     
     Android plugins are based on Cordova-Android, which consists of an
    -Android WebView with hooks attached to it.  Plugins are represented as
    -class mappings in the `config.xml` file.  A plugin consists of at
    +Android WebView with hooks attached to it. Plugins are represented as
    +class mappings in the `config.xml` file. A plugin consists of at
     least one Java class that extends the `CordovaPlugin` class,
    -overriding one of its `execute` methods. As best practice, the plugin
    -should also handle `[pause](../../../cordova/events/events.pause.html)` and `[resume](../../../cordova/events/events.resume.html)` events, along with any message
    -passing between plugins.  Plugins with long-running requests,
    +overriding one of its `execute` methods. As a best practice, the plugin
    +should also handle [`pause`](../../../cordova/events/events.pause.html) and [`resume`](../../../cordova/events/events.resume.html) events, along with any message
    --- End diff --
    
    Link these to events reference?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51802704

--- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
@@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the

## Requirements and Support

Detailed installation instructions are available as part of installation
links above.

export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools

$ 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. 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:

;C:\Development\android-sdk\platform-tools;C:\Development\android-sdk\tools

1. Save the value and close both dialog boxes.

-## 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
--- End diff --

It's pretty self explanatory. Do you think we need to?
```
Available android devices:
Available android virtual devices:
<emulator_name>
```

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51930488
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -31,12 +31,12 @@ platform and back.  For another sample, see also the comments in
     [CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java).
     
     Android plugins are based on Cordova-Android, which consists of an
    -Android WebView with hooks attached to it.  Plugins are represented as
    -class mappings in the `config.xml` file.  A plugin consists of at
    +Android WebView with hooks attached to it. Plugins are represented as
    +class mappings in the `config.xml` file. A plugin consists of at
     least one Java class that extends the `CordovaPlugin` class,
    -overriding one of its `execute` methods. As best practice, the plugin
    -should also handle `[pause](../../../cordova/events/events.pause.html)` and `[resume](../../../cordova/events/events.resume.html)` events, along with any message
    -passing between plugins.  Plugins with long-running requests,
    +overriding one of its `execute` methods. As a best practice, the plugin
    +should also handle [`pause`](../../../cordova/events/events.pause.html) and [`resume`](../../../cordova/events/events.resume.html) events, along with any message
    --- End diff --
    
    @rakatyal Yep, I'll do that
    @nikhilkh Good point!


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-186362161
  
    :ship: it!


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by vladimir-kotikov <gi...@git.apache.org>.

Github user vladimir-kotikov commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51309554

--- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
@@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the

## Requirements and Support

Detailed installation instructions are available as part of installation
links above.

The same as for `JAVA_HOME` - this should be [set by `check_reqs` automatically](https://github.com/apache/cordova-android/blob/master/bin/lib/check_reqs.js#L166)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by nikhilkh <gi...@git.apache.org>.

Github user nikhilkh commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51833427
  
    --- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
    @@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the
     
     ## Requirements and Support
     
    +### Java Development Kit (JDK)
    +
    +Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
    +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](http://developer.android.com/sdk/index.html#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](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) 23.
    +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
    --- End diff --
    
    I don't have better ideas but this will certainly require some maintenance every time we change the API level.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r53528143
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -23,24 +23,17 @@ title: Android Plugins
     # Android Plugins
     
     This section provides details for how to implement native plugin code
    -on the Android platform. Before reading this, see Application Plugins
    +on the Android platform. Before reading this, see the [Plugin Development Guide][plugin-dev]
    --- End diff --
    
    Done


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-185456589
  
    We are not deleting it but referencing it from the main guide. 


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-185457758
  
    Alright, I'll resurrect it and add some stuff about 5.0.0


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51805298

--- Diff: www/docs/en/dev/guide/platforms/android/tools.md ---
@@ -19,206 +19,218 @@ license: >

title: 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](../../overview/index.html), may offer you a greater range of development options than
-the cross-platform CLI tool described in [The Command-Line Interface](../../cli/index.html).
-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](index.html).
+## Building with Gradle

-To enable shell tools for Android, download Cordova from
-[cordova.apache.org](http://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.
+As of **cordova-android@4.0.0**, Cordova for Android projects are built using
+[Gradle](http://www.gradle.org/). For instructions on building with Ant, refer
+to older versions of the documentation.

-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.
+### Gradle Properties

-## Create a Project
+It is possible to configure the Gradle build by setting the values of certain
+[Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html)
+that Cordova exposes. The following properties are available to be set:

-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:
+ * **cdvBuildMultipleApks** (default: false)
--- End diff --

Can we have these in a table? Makes it more readable.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-184817446
  
    Rebased to master and updated to fix the redirects merged in with #494 


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

https://github.com/apache/cordova-docs/pull/471#discussion_r51806333

--- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
@@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the

## Requirements and Support

Detailed installation instructions are available as part of installation
links above.

export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools

$ 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. 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:

;C:\Development\android-sdk\platform-tools;C:\Development\android-sdk\tools

1. Save the value and close both dialog boxes.

-## 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
--- End diff --

Yeah, on second thought, let's skip it.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by vladimir-kotikov <gi...@git.apache.org>.

Github user vladimir-kotikov commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-177849723
  
    @riknoll, +1, makes sense


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-180609791
  
    @rakatyal @nikhilkh @vladimir-kotikov  @infil00p please look this over. I have some more updates to content that are coming, like [CB-10206](https://issues.apache.org/jira/browse/CB-10206). I just want to get the review started now.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by omefire <gi...@git.apache.org>.

Github user omefire commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r52820400
  
    --- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
    @@ -30,278 +30,676 @@ platform-centered shell tools or cross-platform Cordova CLI for
     development. For a comparison of the two development paths, see the
     [Overview](../../overview/index.html).  For details on the CLI, see [The Command-Line Interface](../../cli/index.html).
     
    +
     ## Requirements and Support
     
    -Cordova for Android requires the Android SDK which could be installed
    +Cordova for Android requires the Android SDK which can be installed
     on OS X, Linux or Windows operation system. See the Android SDK's
    --- End diff --
    
    'operation' => 'operating'


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51930197
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -72,7 +72,7 @@ Otherwise, the plugin may compile but still be unavailable to Cordova.
     One instance of a plugin object is created for the life of each
     `WebView`. Plugins are not instantiated until they are first
     referenced by a call from JavaScript, unless `<param>` with an `onload`
    -`name` attribute is set to `"true"` in `config.xml`. E.g.:
    +`name` attribute is set to `"true"` in `config.xml`. For example,
     
         <feature name="Echo">
             <param name="android-package" value="<full_name_including_namespace>" />
    --- End diff --
    
    I believe the `"android-package"` param is used for defining the Java package for your app so that the directory structure gets created correctly. See an example usage here: https://github.com/apache/cordova-plugin-camera/blob/master/plugin.xml#L64


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51803655
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -118,7 +118,8 @@ exception names as much as possible.
     The plugin's JavaScript does _not_ run in the main thread of the
     `WebView` interface; instead, it runs on the `WebCore` thread, as
     does the `execute` method.  If you need to interact with the user
    -interface, you should use the following variation:
    +interface, you should use the [Activity's `runOnUiThread`][ref-runonuithread]
    --- End diff --
    
    This appears very weird on the github rich diff. I hope it's better on the website?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r51802634
  
    --- Diff: www/docs/en/dev/guide/platforms/android/index.md ---
    @@ -32,276 +32,152 @@ development. For a comparison of the two development paths, see the
     
     ## Requirements and Support
     
    +### Java Development Kit (JDK)
    +
    +Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
    +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](http://developer.android.com/sdk/index.html#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](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) 23.
    +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](https://github.com/apache/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](http://developer.android.com/about/dashboards/index.html).
    -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
    -[cordova.apache.org](http://cordova.apache.org). 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
    -plugins.
    -
    -## Install the Java Development Kit (JDK)
    -
    -Install [Java Development Kit (JDK) 7](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
    -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](http://developer.android.com/sdk/installing/index.html?pkg=tools) or [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio). Procceed with `Android Studio` if you plan 
    +Install the [Android Stand-alone SDK Tools](http://developer.android.com/sdk/installing/index.html?pkg=tools) or [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio).
    +Proceed with Android Studio if you plan on
     developing new Cordova for Android plugins or using native tools to
    --- End diff --
    
    Yeah all right.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by rakatyal <gi...@git.apache.org>.

Github user rakatyal commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-185450815
  
    Are we adding link to the 'Upgrading' article?


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by omefire <gi...@git.apache.org>.

Github user omefire commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r53248266
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -23,24 +23,17 @@ title: Android Plugins
     # Android Plugins
     
     This section provides details for how to implement native plugin code
    -on the Android platform. Before reading this, see Application Plugins
    +on the Android platform. Before reading this, see the [Plugin Development Guide][plugin-dev]
    --- End diff --
    
    I think we should rename it. any ideas? @rakatyal 


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/471#discussion_r53242147
  
    --- Diff: www/docs/en/dev/guide/platforms/android/plugin.md ---
    @@ -23,24 +23,17 @@ title: Android Plugins
     # Android Plugins
     
     This section provides details for how to implement native plugin code
    -on the Android platform. Before reading this, see Application Plugins
    +on the Android platform. Before reading this, see the [Plugin Development Guide][plugin-dev]
    --- End diff --
    
    Is that our official naming convention? I'm inclined to leave it as is until we combine all the plugin guides into one.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

[GitHub] cordova-docs pull request: CB-10332 Android Guide Improvements

Posted by riknoll <gi...@git.apache.org>.

Github user riknoll commented on the pull request:

    https://github.com/apache/cordova-docs/pull/471#issuecomment-180021130
  
    @nikhilkh yes, I think the plan is to add a debugging section.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org