Shazron's Cordova (aka PhoneGap) Blog

at Adobe Systems Inc.

PhoneGap Xcode 4 Template (beta)

with 37 comments

UPDATE: PhoneGap includes the Xcode 4 template now, download it from
View the screencast below (best in full-screen, in HD).
Also, you can read the wiki article.

Xcode 4 template specs are undocumented and buggy. So, there are issues:

    • We cannot automatically include the “www” folder in the template – the user has to add it in manually (a quick drag and drop). I added in checks and warnings if users try to run the app without adding this in.
    • Some files, like .h and the -Info.plist file, are included in the ‘Copy Bundle Resources’ build phase by the template. No biggie during run-time, but for those with OCD they will want to remove these from the Build Phase (if only to get rid of the warning).
    • Because Xcode 4 does not expand tildes (~), I cannot add a reference to the PhoneGap.framework in the user’s home folder, so I added it to a shared location /Users/Shared which has r+w permissions for everyone (the common folder /Library/Frameworks needs admin privileges). It was added here so users without admin privileges can still use PhoneGap.framework, and by extension, the Xcode 4 Template.


    • beta1 – Initial release
    • beta1.1 – Bug fix for issue #81 (moved framework from /Users/Shared/Library to /Users/Shared/PhoneGap)
    • beta1.2 – Made /Users/Shared/PhoneGap writable to everyone
    • beta1.3 – Fixed Template not copying over the ‘www’ directory from the framework location (happened only for users that only installed beta1.3 and didn’t migrate from an earlier beta version). This version was tested on a clean Mac OS X 10.7 Lion DP3 system running Xcode 4.1 DP5, and works great.
    • beta2 – (UPCOMING) add AppleScript in the project Run Script build phase to get Xcode to automatically add the ‘www’ folder for you

Written by shazron

May 5, 2011 at 11:57 pm

Posted in phonegap, xcode

37 Responses

Subscribe to comments with RSS.

  1. If you get an error running the project after creating the project from the template (“The selected run destination is not valid for this action.”), this is an Xcode 4 bug where it changes the platform to Mac OS X after template creation.

    Close down the project, and launch it again, to fix it.


    May 6, 2011 at 12:02 am

    • great post and so far this has been a big help. My main problem right now is that I can’t seem to add a reference for phonegap.framework (binary) Some of my projects are looking for this. Is this a separate download? I’m running clone Xcode 4.3.1. The phone gap install looks right after doing the “www” folder reference, etc a basic app will come up and give me the “Cordiva is working” message. But some of my plugins are looking for phonegap.framework

      Any help would be appreciated!! Allen


      May 9, 2012 at 1:39 pm

      • You will have to upgrade your .framework reference. In the Cordova .dmg, file there is a Guides folder with guides regarding upgrading your plugins/project.


        May 11, 2012 at 6:22 pm

  2. Hi Sharzon

    thanks for putting this out. However I’m getting a installation failed summary error at the end of the install. Any ideas how to fix?




    May 6, 2011 at 1:18 am

    • @dave Might be a permissions error. When you run the Installer and get the error, don’t close it down. Go to the Window menu, select “Installer Log”, then select “All Logs” in the dropdown, then click on the “Save” icon in the toolbar of the Log window, then email the log to shazron at nitobi


      May 6, 2011 at 1:23 am

  3. @shazron Thanks. I just sent it to you.


    May 6, 2011 at 1:31 am

  4. Found a bug (with the help of Dave). Adobe AIR, with perfect timing, of all the days, tonight, decided to write to (and create) “/Users/Shared/Library/Application Support” which of course created /Users/Shared/Library with read+write permissions for Admin users only. This meant that Standard users could not install the PhoneGap framework.

    The fix is to do a “Get Info” on your /Users/Shared/Library folder and give r+w permissions to everyone. This will require Admin privileges of course.

    I am going to modify the framework path to a unique to PhoneGap one, to get around this issue.


    May 6, 2011 at 4:16 am

  5. The bug from comment #5 is tracked here:


    May 6, 2011 at 4:19 am

  6. I had the same problem.


    Run the following commands in terminal before running the installer:

    sudo mkdir /Users/Shared/Library/Frameworks
    sudo chown USERNAME /Users/Shared/Library/Frameworks

    (Replace USERNAME with your username)
    If you don’t know what your username is run:

    Scott Murphy

    May 6, 2011 at 4:28 am

  7. OR
    sudo chmod ugo+rw /Users/Shared/Library
    (where USERNAME is a user with Admin privileges)


    May 6, 2011 at 4:42 am

  8. Issue #81 fixed, see blog update (download link, and release notes) above.


    May 6, 2011 at 5:44 am

  9. Note: My problem was different. The directory
    did not exist and the installer was unable to create it because it was getting permission denied.

    That is why I had to run sudo mkdir first.

    Scott Murphy

    May 6, 2011 at 7:10 am

    • @Scott Blog was updated before your comment, see comment #9 (beta1.1 installer is out).


      May 6, 2011 at 7:15 am

  10. To clarify, beta1.1 does not use /Users/Shared/Library/Frameworks anymore


    May 6, 2011 at 7:16 am

  11. Hi Shazron,

    I’ve watched the video. I’ve installed beta1.2. It installs fine. I’m able to make a new PhoneGap project.

    What is happening though is when I right click on my project there is no www folder to select. I see the xcodeproj file but no www folder.

    The error I’m getting looks similar to the one you show in the video.

    The www folder /Users/Justin/Desktop/Test/www does not exist. Copying sample.
    cp: /Users/Shared/Library/Frameworks/PhoneGap.framework/www: No such file or directory
    Add /Users/Justin/Desktop/Test/www as a folder reference in your project.
    Just drag and drop the folder into your project, in Xcode 4.

    What am I missing?


    May 6, 2011 at 7:07 pm

    • Darn it. This is what happens when you fix something late at night! Forgot to change the build script in the template 😦 if you can change it yourself, change the cp command from /Users/Shared/Library/ to /Users/Shared/PhoneGap/ it should work after. Will fix in beta1.3 sorry 😦


      May 6, 2011 at 7:25 pm

  12. Not sure where that cp command change would be done or else I’d give it a shot at changing it.

    I’ll wait for the beta1.3 then. Any idea when you’ll be able to get to it?



    May 6, 2011 at 7:36 pm

    • It’s the section in the screencast where I discuss “Other Issues”, there is a Run Build Script item there. Currently mobile, so I can’t get to this until the evening.


      May 6, 2011 at 7:47 pm

    • Also, updated the source so if you want to build the installer yourself… Unfortunately there is so much I can do through Github’s web interface…


      May 6, 2011 at 7:58 pm

  13. Got it – under Run Script. That did it.

    Thank you for the video, very helpful. I’ve found PhoneGap to be excellent. Nice to be able to make the template now again in XCode 4. Thank you again.

    Is your blog here the right place to stay current with all things PhoneGap related?


    May 6, 2011 at 7:59 pm

  14. When do you estimate a non-beta version will be available?

    Jorge Tapia

    May 6, 2011 at 10:58 pm

  15. beta1.3 posted (also check out the Release Notes for upcoming beta2 feature)


    May 7, 2011 at 5:19 am

  16. @shazron that’s good to know, keep up the great work, I love PhoneGap 😀

    Jorge Tapia

    May 7, 2011 at 8:05 pm

  17. I don’t know if this is related to PhoneGap or not, but I thought I’d ask here.

    When I run my ‘TestApp’ from Xcode on my iPad. It builds ok and looks like it is going to be fine, but then a window comes up saying – Error Starting Executable ‘TestApp’.

    I read online something about editing the scheme and setting the Debug option there to none. That does remove the error but then the app doesn’t launch on the iPad.

    Any help would be appreciated. Thanks.


    May 9, 2011 at 10:00 pm

  18. Shazron,

    Could you tell me what is needed, when using the iPad, to have the splash image use the iPad image you want? I replaced the Default~iPad.png with the one I want to use, but it looks stretched and then it quickly goes to the Default@2x.png image.



    May 10, 2011 at 4:44 pm

    • Projects that are created using the Xcode 4 template do not do what you describe, I explicitly fixed this and tested this. If you are talking about the Xcode 3 template, please use the Google Group for off-topic discussion.

      That being said, most likely is, you didn’t include the right assets in your project – make sure it is added to the project file itself, not just in your folder on disk.


      May 10, 2011 at 7:15 pm

  19. Shazron,

    Thanks for the reply, and sorry if this is not the right place to further the discussion.

    After I installed the latest Phonegap and the beta you have here. What I did was add these files to the “splash” folder in the project:
    Default.png – transparent png
    Default-Portrait.png – nothing in this image just white background
    Default-Landscape.png – my main “splash” page image

    Once I did that it worked and the Default-Landscape image was used. I’m not completely clear as to why this was needed, but that is what I did and it seemed to work. If there is a better way please say so. I did not add Launch Image (iPad) in the plist. That didn’t seem to make a difference.

    My app works in the simulator and on the iPad. Just trying to resolve a situation where it says – Error launching remote program: failed to get the task for process…when I launch it in the simulator.

    Thanks for any feedback, very much appreciated.


    May 10, 2011 at 8:09 pm

  20. Edit.

    I meant to say, when I launch it in the device from Xcode, not the simulator. The simulator does not show that error.


    May 10, 2011 at 8:11 pm

  21. Again, this is off topic. Please file an issue at


    May 10, 2011 at 11:16 pm

  22. Strange thing, i dont have a PhoneGap-based-application when creating new project in Xcode, althrough all files are in place.
    (ive just installed latest xcode 4.0.2)
    so i just copy template folder, rename and open it in Xcode


    May 15, 2011 at 8:19 pm

  23. “There were errors with the installation. You may want to try installing again.”

    Any ideas why I get this error message every time I try to install (beta 1.3)


    May 17, 2011 at 11:08 am

    • Post the installer log. When you run the Installer and get the error, don’t close it down. Go to the Window menu, select “Installer Log”, then select “All Logs” in the dropdown, then click on the “Save” icon in the toolbar of the Log window, then email the log to shazron at nitobi


      May 17, 2011 at 7:25 pm

  24. PhoneGap released – download from
    Includes the Xcode 4 template (with one minor change – it does not fail at first run, but just gives a warning)


    May 24, 2011 at 8:30 pm

  25. Shazron,

    I don’t know if this question is related to your xcode 4 template download here, or not. I just want to make sure I have the right stuff. My question is this – after downloading and having xcode 4. My phonegap project files (on the left in xcode) don’t show the .m class files, a separate .xodeproj folder, project plugins.

    This is just a guess, but is what I’m “missing” a part of xcode 3 or something called the phonegaplib (not sure what that is exactly)?

    Thank you for clarifying.


    June 24, 2011 at 10:36 pm

  26. @Justin the Xcode 4 template has a different layout, and does not use PhoneGapLib anymore because of Xcode 4 Template restrictions (no way to add it). It uses a static framework.


    June 24, 2011 at 10:39 pm

  27. Do you feel that there is a disadvantage in using the Xcode 4 template then, and one should still use Xcode 3?

    I’m asking from a place of not really knowing what the PhoneGapLib is, but I suppose if you had to make changes to some of the PhoneGap .js files is that where they would be?

    Just trying to get a better handle on it. Thanks for explaining.


    June 24, 2011 at 10:55 pm

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: