Shazron's Cordova (aka PhoneGap) Blog

at Adobe Systems Inc.

Improvements in Cordova 2.0.0 for iOS

with 46 comments

With the release of Apache Cordova 2.0.0 there are some significant changes for the iOS platform. We’ve removed the problematic Xcode templates, and updated our support to iOS 4.2 and greater only. Support for ARC (Automatic Reference Counting) was planned but pushed to a later release (tentatively scheduled for 2.1.0).

1. Removal of the Xcode Templates

Initially we had Xcode 3 template support, so when Xcode 4 rolled in, we updated our templates to support Xcode 4. However, because of Xcode 4’s template limitations, this resulted in a poor user experience when first creating a new Cordova-based Application. The Xcode 4 template format is undocumented – we couldn’t add a folder reference nor add a sub-project, so we had to include a pre-built Cordova.framework and also make the developer copy in the www folder manually.

A developer had to:

  1. Build once to copy in the “www” folder (from the Cordova.framework) into their project folder on disk
  2. Locate the “www” folder in their project folder on disk
  3. Drag in the “www” folder to their project icon in Xcode

This was very error-prone and did not lead to a good “first-run” user experience. Shipping a pre-built binary (Cordova.framework) also causes problems for certain systems (unreproducible crashes with Reachability) and problems with the inability to debug errors in the Cordova library itself.

The Xcode templates have been replaced by our new command-line utility to create a new project.

2. Create a new Cordova-based Application project from the command line

Install Cordova-2.0.0.pkg and then follow the Getting Started Guide, then see the procedure at

Consult this blog post “PhoneGap 2.0 Getting Started” as well for any errors you encounter.

This template creation method eliminates all the problems with the Xcode 4 template. Create the new project, and you are ready to go immediately. Your new project also links in CordovaLib as a sub-project now, so you have access to the Cordova source code for debugging if you need to.

Moving to a command-line interface also allows for greater flexibility in tooling and packaging.

3. Debug, emulate and view the console log of your Cordova project from the command line

When you create a new Cordova-based application project, you will notice that there is a new “cordova” folder included in your project folder. In there, there are three scripts: debug, emulate and log.

Navigate to the cordova folder from, and you can type the appropriate commands to use these scripts. Using these scripts, you will never need to launch Xcode again. Details on what these scripts do are at

4. Support of iOS 4.2 and greater only (and drop iOS 3 support)

What iOS 4 allows Cordova developers to do now is to include the usage of blocks in their plugins. Also, the iOS SDK API is switching to using blocks in most of the framework APIs, and it would be great for Cordova plugins to take advantage of them. JavaScript developers will be familiar with the power of using blocks, they are similar to how they are used in JavaScript (closures and callbacks).

Also, iOS 4.2 specifically has built-in support in JavaScript for WebSockets, the DeviceOrientation API (accelerometer, gyroscope), new JavaScript data types, XHR-2 support, and others. See this blog post for more details.

5. Xcode 4 and Lion & Mountain Lion support only

Some developers are still using Snow Leopard (10.6) – which only has Xcode 4.2 (iOS 5.0 SDK). With the upcoming release of the iOS 6 SDK, there doesn’t seem to be any Snow Leopard support for it. A SDK release is always coupled with a version of Xcode, and all the newer versions of Xcode are for Lion (10.7) and Mountain Lion (10.8) only. The Apple App Store will only accept apps that are built using the latest version of the iOS SDK. When iOS 6 is released, this will preclude Snow Leopard (10.6).

Next steps:

Currently there is still a GUI based installer that installs CordovaLib into your home folder’s Documents sub-folder, and it also updates the $(CORDOVALIB) Xcode variable. The GUI installer will be removed in a future release, and installation will be through the command-line as well. This will allow us to version and package Cordova iOS through homebrew, for example.


Written by shazron

July 20, 2012 at 6:38 am

Posted in cordova, phonegap, xcode

46 Responses

Subscribe to comments with RSS.

  1. […] Improvement to iOS app creation – We’ve implemented significant changes for the iOS platform. Get a deeper dive into all the changes from Shaz, our PhoneGap iOS lead developer. […]

  2. […] Mac tooling has been improved and no longer depends on Xcode templates. Instead, you create a new project at the command line. […]

  3. I’m new to Cordova, but not to iOS, and started playing around with Cordova 2.0.0 today. One thing that I cannot figure out is how to run a Cordova on a real iOS device (properly provisioned etc of course) as you would if you were developing in XCode. Is this possible with the new release? If so, how? Thanks!


    July 20, 2012 at 9:14 pm

    • Not sure what you are asking — are you asking on how to debug your HTML+CSS+JS? There is nothing in Xcode that allows this, but in iOS 6 it is possible:

      For now you can try using iWebInspector ( or Weinre (


      July 21, 2012 at 12:38 am

      • I am simply asking how I can plug in an iOS device to my computer and run the Cordova app on it, rather than use the simulator. Much of app testing can be done in the simulator of course. Some things, e.g. accelerometer, location services, etc., require a real device. The only way I see of running a Cordova app in version 2.0 is via the debug or emulate scripts, both of which launch the simulator. Is there a way to run the app on the device itself, as you can in XCode?

        Thanks for those links though, definitely appreciated.


        July 21, 2012 at 12:54 am

    • To run on a real device you can open the xcode project with the XCode GUI and do all the normal provisioning steps.

      Chris Brody

      July 29, 2012 at 8:45 pm

    • Ah ok – unfortunately there is no (current) way with the command line tools to deploy to a device. I couldn’t find anything regarding this.


      August 10, 2012 at 9:55 pm

      • ” you will never need to launch Xcode again. ”

        Except if you want to create an app that needs to get in the app store.


        August 16, 2012 at 7:21 am

  4. Although I’m really excited this is moving toward command line, I’m having a lot of trouble working with this release.

    First, I’m not totally sure how to reference it. It’s not really bundled as a command line tool, it’s just a random folder. So copying the executable or symlinking the folder to /usr/local/bin doesn’t work as it cross-references other items in the folder. This means any time I run it, it’s a long awkward path that has to be typed out.

    Also, I’m building initially for iOS and it appears as if it doesn’t build out of xcode, so I tried building with the command line debug task. However, this task is asking me for the /Developer folder, which is no longer installed from Xcode 4 forward. Any suggestions?


    July 21, 2012 at 1:37 am

  5. Can someone please make a video and show me step by step how to make a new iOS Xcode project with 2.0? I unfortunately do not understand the instructions linked in the article. I used to just install something, open Xcode, and drag a www folder. Seemed simple enough. This new way is like going from the Mac to the Apple II.

    Jim Bakhaffari

    July 21, 2012 at 5:14 am

  6. I’m just upgrading from 1.7 to 2.0, and encountered this issue:

    Thought it might be a good idea to add it to the upgrade guide.

    Otherwise, thanks for all your hard work!

    Avidan Chen

    July 23, 2012 at 12:24 pm

    • Thanks – yeah I find sometimes a good Xcode restart fixes things 🙂


      August 10, 2012 at 10:06 pm

  7. I don’t like that the lib installs to my Documents now


    July 24, 2012 at 10:31 am

    • It has always installed to your Documents. You can move it to wherever you want, actually – just have to update the CORDOVALIB Xcode variable in Xcode Preferences -> Source Trees. With 2.1, there is no GUI installer and you can put and install it wherever you want.


      August 10, 2012 at 9:58 pm

  8. previous version worked well but…

    I cannot get the 2.0 command line tool to create a project. Is this entered correctly?
    ./create ~/Desktop/HelloWorld com.helloworld HelloWorld

    All I get is the following:

    usage: cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file target_file
    cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file … target_directory


    July 25, 2012 at 6:49 am

    • There was a bug that your path cannot contain spaces – this has been fixed for the next release. You can download the latest scripts from the Github repo if you want.


      August 10, 2012 at 10:08 pm

  9. I had started work on an app a couple weeks ago using v1.9. Are there any plans on releasing a guide on how to best upgrade projects to v2.0? Or would it recommended to just create a new 2.0 project and port my 1.9 code over?

    Matt K

    July 25, 2012 at 6:39 pm

  10. I have just installed Cordova 2.0 for developing iOS apps, but when i run the xproj file in Xcode 4.4 I get a lot of issues reported. CordovaLib has 21 issues, and the sample project HelloWorld has 3 issues. The issues include Format String Issue, Semantic Issue, Logic error, and a couple of Deprecations. The sample app did launch, but this seems to be a lot of errors. Should I be worried?!



    July 26, 2012 at 12:22 pm

    • It’s harmless, the Xcode 4.4 compiler is more strict. This has been fixed and will not show the warnings in the next release.


      August 10, 2012 at 9:59 pm

  11. With the greatest of respect to the developers, this is something of a step backwards in my opinion. If you take a look at your own blog post – it previously took 3 steps, all of which focused around dragging the www folder into xcode.

    This has been replaced with dealing with terminal and turned 3 steps into several. I can see this putting off new users trying to get cordova/phonegap working for the first time.


    July 27, 2012 at 9:09 am

    • I understand your frustration, this is part of the strategy for all the platforms, not just iOS. Making it command line opens up more possibilities, including (our own, or third-party) GUI installers in the future.


      August 10, 2012 at 10:00 pm

    • I agree, with Dave. The command line is very frustrating, I also have an additional problem trying to create extra directories, it will only accept ~/Desktop/Folder1 and not ~/Desktop/Folder1/Folder2.
      I liked the ease of use by dragging my files in the www folder. I am now very unsatisfied with the new setup and complicated upgrading…

      6mwt app

      August 25, 2012 at 3:50 pm

  12. is a bit confusing.

    for example, it doesn’t mention you have to open the .dmg to find a bunch of those files.

    also, the ./create command line shows path, bundle, and and project name, but the black box immediately below talks about path, package name, project name instead. Are bundle and package name the same thing?

    and then the example terminal window below lists four parameters, whereas you’ve only discussed three.


    August 2, 2012 at 8:14 pm

  13. I haven’t updated in a while – I’m still running Xcode 4.2 on Snow Leopard (10.6.8) and I’m using Phonegap 1.3. Is it required that I upgrade to Xcode 4.4 (and therefore also to Mountain Lion) and to the latest Phonegap/Cordova? When will Apple require us to use iOS SDK 5.1 or 6?

    If not, and I can still use earlier Phonegap releases, I’m a bit confused as to how the numbering of the Cordova and Phonegap releases work. For example, when I look at the install guide for Cordova 1.5.0 ( it says to install the “latest Phonegap”. Should that also be PG 1.5.0?

    Steve Romalewski

    • No, you can use Xcode 4.3.3 or 4.4 for Lion. When iOS 6 is released – you cannot use Snow Leopard anymore. If you are on Lion you should be safe. Cordova == PhoneGap – think of it this way, Cordova is the engine that powers PhoneGap, like how WebKit powers Apple Safari and Google Chrome.


      August 10, 2012 at 10:05 pm

  14. […] Improvements in Cordova 2.0.0 for iOS by Shazron Abdullah […]

  15. […] Improvement to iOS app creation – We’ve implemented significant changes for the iOS platform. Get a deeper dive into all the changes from Shaz, our PhoneGap iOS lead developer. […]

  16. Ok I’m very new using phonegap… I was using the latest version before upgrading my os …
    Now I’m stucked and can’t even start a project… Always got error .. “” no file in directories… Unable to load…. Etc… Can someone please
    Help me… I follow the Video tutorial in utube and I even create exactly the same folders the tutor was using but no luck…..please help…
    Command line is installed


    August 12, 2012 at 1:12 pm

  17. “you will never need to launch Xcode again.”

    That’s a bad thing, not a good thing.

    Maybe it’s not so bad and just a project-start-step?
    Let’s see and find out.


    August 16, 2012 at 7:23 am

    • I did the “/Users/me/Documents/CordovaLib/bin/create /Volumes/Workdisk/project/app AppName thing.
      It made 3 folders and a AppName.xcodeproj that opend and compiled in Xcode with no problems.



      August 16, 2012 at 7:39 am

      • “I did the “/Users/me/Documents/CordovaLib/bin/create /Volumes/Workdisk/project/app AppName thing” …

        well, but this is exactly the “thing” where the users (like me and many posters above are struggeling).

        Any hints where to start to get familiar with command-line-tools?
        What leads “to a good “first-run” user experience” (as the author of this articel is insisting)?




        August 22, 2012 at 2:27 pm

      • Which part are you having trouble with? Let me know I can help out.


        August 24, 2012 at 8:08 pm

  18. I get this error when I run ./create in the Terminal…
    /Volumes/Cordova-2.0.0/bin/replaces: line 28: tmpFile: Read-only file system
    mv: tmpFile: No such file or directory
    I don’t know what the problem is


    August 23, 2012 at 5:02 pm

    • i forgot to add this…I can’t figure out why it’s saying no such file or directory…it actually creates the xcodeproject…but a lot of the files and references in Xcode are still referencing __Testing__ instead of HelloWorld…like it got part way through the creation process when it got that error and didn’t finish

      any help?


      August 23, 2012 at 5:22 pm

      • The easiest way is to copy it to your desktop….and follow this:
        Create a folder that you gonna all Test and another folder inside the first folder and name it App(just examples)….
        Now drag and drop the bin folder in your terminal on the dock and then type then copy and paste this in your terminal: ” .create ~/Desktop/Test/App com.helloworld YourAppName ” and then press enter
        Fallow this:…..

        Marius Lalsomde

        August 24, 2012 at 10:58 pm

    • Copy the bin folder to your hard disk first, instead of from the .dmg mounted volume.


      August 24, 2012 at 8:05 pm

      • Thanks…I had in fact copied it to my hard drive like the instructions said…but then immediately went back to the .dmg folder and used the bin folder there instead.


        August 25, 2012 at 8:35 am

  19. […] Source (check #4) […]

  20. Hello
    My app is not working with Cordova (device and simulator). I am running Cordova2, Xcode 4.3 and Require.Js. I believe my problem is the ‘deviceready’ step.
    I would like to integrate the sample code with my code that runs in my browser:

    SAMPLE with PhoneGap2:
    var start = {
    initialize: function() {
    bind: function() {
    document.addEventListener(‘deviceready’, this.deviceready, false);
    deviceready: function() {
    // note that this is an event handler so the scope is that of the event
    // so we need to call, and not‘deviceready’);
    report: function(id) {
    console.log(“report:” + id);

    MY code called when require.js loads:
    define([‘app’], function(app) {
    $(document).ready(function() {
    console.log(“DOM IS READY”);

    Thanks a lot!


    September 20, 2012 at 8:48 pm

  21. […] aren’t natively supported by the browsers in Android or older versions of Cordova under iOS, which means you’ll need to use a PhoneGap plugin if you want to use them on the […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: