Cordova/PhoneGap Version Confusion

November 7, 2014By 1 Comment

confused-dog

The different versions of all things Cordova and PhoneGap can be pretty confusing to keep track of at times. Everyone may not be aware that there have been some recent decisions and changes made to how things will be handled with the Cordova project going forward.

In summary, the platform versions (ios, android etc) are now independent of CLI version (will no longer match) and the CLI version will likely be rising more rapidly. Read the whole thread if you’re curious about why this changed. This post is an attempt to explain the different versions and how you can find them for your projects.

Cordova Versions

We’ll start with Cordova since it’s the underlying version to so many different things including other vendors’ offerings so you should always be aware of how to find these versions first and foremost.

  • Overall Version – find yours by typing:

    $ cordova -v

    When you install cordova from npm or click the download button from Cordova.io, these versions are the same (currently 4.0.0) and represent a blanket identifier that includes:

    1. The CLI (command line interface) Tooling Version – The version of the tooling and commands you’re using to create, build and deploy your apps. For instance, if a new option is added to the $ cordova create command to allow you to specify a template URL.

      Use the same command as before to find the CLI version:

      $ cordova -v

      **Note: this number will always match the overall version.**

    2. Set of Platform Versions – This is basically the version of cordova.js file copied in at build time for each supported platform (amazon-fireos, android, blackberry10, browser, firefoxos, ios, windows etc), since each has its own specific code.

      For instance, the current 4.0.0 version will install iOS 3.6.3, android 3.6.4, browser 3.6.0, firefox os 3.6.3 etc.

      You can find the platform versions with the $ cordova platform list command such as:

      $ cordova platform list
      Installed platforms: android 3.6.4, browser 3.5.2, firefoxos 3.6.3, ios 3.6.3
      Available platforms: amazon-fireos, blackberry10

      To install a specific version, first remove the current one if a version was previously added via:

      $ cordova platform remove ios

      Then add the one you want by using the @ syntax:

      $ cordova platform add ios@3.7.0

      Tip: Always use the $ cordova platform remove command versus manually deleting a platform folder from the file system or you will likely cause yourself in some sort of pain down the road. :)

      NOTE: If there ever seems to be a mismatch with what’s returned from the platform list command, you can always just open the cordova.js file copied into the platforms www folder (for example ../platforms/ios/www/cordova.js) to see what’s specified in the following variable:

      var PLATFORM_VERSION_BUILD_LABEL = '3.7.0';

  • Plugin Version: Each plugin (file, device, media, contacts etc) also has a version. To see the versions of plugins for a given project, use the $ cordova plugin list command such as:

    $ cordova plugin list
    org.apache.cordova.camera 0.3.3 "Camera"
    org.apache.cordova.contacts 0.2.14 "Contacts"
    org.apache.cordova.device 0.2.12 "Device"

    To install a specific version, use the @ syntax:

    $ cordova plugin add org.apache.cordova.camera@0.2.9

    or to ensure the latest plugin version, use the latest alias:

    $ cordova plugin add org.apache.cordova.camera@latest

    Tip: To quickly search the plugin registry and get the id for a plugin, use the $ cordova plugin search command with any search term:

    $ cordova plugin search contacts
    com.blackberry.pim.contacts - BlackBerry 10 Contacts APIs
    com.kolwit.pickcontact - Native contact-picker overlay, accessing the address book
    org.apache.cordova.contacts - Cordova Contacts Plugin

    Another Tip: To get all the data including versions available for a specific plugin, use the $ plugman info command with the id of the plugin in question (assuming you have plugman installed, and you should if you don’t):

    $ plugman info org.apache.cordova.camera

    You’ll get a ton of info back and will need to scroll up a bit to find the versions array, such as:

    versions:
    [ ‘0.2.1’,
    ‘0.2.3’,
    ‘0.2.4’,
    ‘0.2.5’,
    ‘0.2.6’,
    ‘0.2.7’,
    ‘0.2.8’,
    ‘0.2.9’,
    ‘0.3.0’,
    ‘0.3.1’,
    ‘0.3.2’,
    ‘0.3.3’ ]

    The Plugins Registry also lists all the versions for any given plugin in a drop-down list on the top right corner.

    registry

  • All of the above commands work with the phonegap CLI as well since it is just a wrapper around the Cordova tooling to provide some additional features. If you’re an Ionic Framework user, the same applies for their CLI. So you could do $ phonegap platform list and $ ionic platform list etc.

PhoneGap Versions

The main thing to know about the PhoneGap (Adobe-specific CLI) side of things is that the above applies except the overall PhoneGap version and CLI version (which are the same) are generally a bit behind compared to the overall Cordova version due to the fact that the PhoneGap team needing to update it after the cordova version is available and testing needed to ensure compatibility with different things. Similar to cordova, to find the overall/CLI version of phonegap installed, type:

$ phonegap -v
3.6.0-0.21.19

When using the PhoneGap CLI versus the Cordova CLI, again the set of platforms can be different and will be based specifically on the version number above since it encompasses both the CLI and the certain set of platform versions as I explained previously, such as:

$ phonegap platform list
Installed platforms: android 3.6.3, firefoxos 3.6.3, ios 3.6.3
Available platforms: amazon-fireos, blackberry10, browser

In this case some of the platform versions happen to match what I got from 4.0.0 in the top of the post since no independent platform releases were done between 3.6.0 and 4.0.0 apparently. The point is that you should never assume they will be the same between overall versions.

** NOTE: You can still add a specific platform version using the phonegap CLI with the @ syntax as described above:

$ phonegap platform add ios@3.7.0

NOTE: The versions of platform to overall version can be particularly confusing since they may be close or similar in numbers. This is especially true right now with the PhoneGap overall/CLI version since it’s at 3.6.0 and many of the platforms are 3.6.x as noted above. Keep the context in mind when reading about a particular fix being in a version since it may just be referring to the platform version (ios etc) versus the overall.

For instance, this morning I installed iOS v3.7.0 specifically to fix something since iOS 3.6.3 is the current default iOS version installed when you do $ npm install cordova and then add the iOS platform. This is because iOS v3.6.3 is the default version for overall/CLI version 4.0.0 currently the latest released, but iOS 3.7.0 will be the default when the overall (and CLI) version 4.1.0 is released.

PhoneGap Build Versions

PhoneGap Build supports an overall version of PhoneGap to do its compiling which is also typically behind the latest Cordova version a bit to ensure plugins are tested and compatible etc. For instance, right now it’s v3.6.3 which happens to match the PhoneGap Overall/CLI version, but this is not always the case. You can find the version used for your PhoneGap Build project in the UI for a given project such as shown with the arrow below:

pgb-version
You may also notice a warning on the project to update if it’s an older project and a new version is available or recommended due to an important fix as shown in yellow above.

To build with a specific version of PhoneGap, specify it in the config.xml preferences tag:

<preference name="phonegap-version" value="3.5.0" />

PhoneGap Build – Plugin Versions

You should also be aware of the version of plugin being used when building with PhoneGap Build. See this link for the latest default versions of plugins used by PhoneGap Build. It’s recommended to specify the plugin version you want to use in your config.xml as well in the tag explained here.

Stay Informed!

I HIGHLY recommend you follow these accounts on twitter to stay on top of all new updates:

Twitter

Tip: Even if you find twitter a distraction, you could set up an id just to follow important account as these since it truly is the easiest way to stay on top of the latest.

Blogs / News / Mailing Lists

Related Links

Please also see these related links to resources from my colleague Ray Camden in relation to all of the above:

Filed in: AndroidCordovaioniciOSMobile DevelopmentPhoneGap Tags:

About the Author ()

Comments (1)

Trackback URL | Comments RSS Feed

  1. Nice article as usual :)

    I’d love to be able to upload my plugins to the Cordova plugin registry so users can easily find and install them as you described, but this bug is holding me back since day 1: https://issues.apache.org/jira/browse/CB-7079

    Thanks,
    Eddy

Leave a Reply