Compile PhoneGap Source Code in Your iOS PhoneGap Project

This post explains how to configure an iOS PhoneGap project to include the open source PhoneGap code as a sub-project in XCode 4. I successfully achieved this with PhoneGap 1.5 through 1.61. I’m not sure if it works with other versions of PhoneGap.

I included the PhoneGap source code when troubleshooting a consistent crash on the iPad as the camera app opened. Including the Cordova source code allowed me to step through the camera related code in XCode.

Note: As of PhoneGap 1.5 much of the PhoneGap code had objects renamed from “phonegap” to “cordova”. See this blog post for the story behind this name change.

Steps to configure an iOS PhoneGap project to include the Cordova source

  • Create a new Cordova-based Application and get the www folder configured. For now I will refer you to the PhoneGap site for the initial sequence of steps. Note that these steps apply only to setting up Cordova 1.5 and above with Xcode 4. Follow these instructions from the PhoneGap site.
  • For the remaining steps, I will assume you created a project named “CordovaSampleApp”. (Substitute your project name in the instructions if different)
  • Select the framework reference “Cordova.framework”, right click and select “Delete”.
  • You will be asked if you want to move the file “Cordova.framework” to the trash. Select “Remove Reference”.
  • Open the Finder and navigate to the location of the Cordova Source Code. It is installed at ~\Documents\CordovaLib by default.
  • Drag the CordovaLib.xcodeproj file from the Finder on top of the Project node within XCode.
  • You should see a project named “CordovaLib.xcodeproj” indented underneath the CordovaSampleApp project node.
  • Select the CordovaSampleApp project node. Then, select its “Target” to display the related configuration tabs (Summary, Info, Build Settings, Build Phases, Build Rules).
  • Select “Build Phases”. Then, expand the “Link Binary With Libraries” group. Select the “+” at the bottom of this group to add a framework.
  • Under “Workspace”, select “libCordova.a”. Select the “Add” button. “libCordova.a” may be red. This is expected.
  • Expand the “Target Dependencies” group. Select “CordovaLib” (nested underneath the framework by the same name).  Select the “Add” button.
  • Select the “Build Settings” tab (next to “Build Phases”).
  • To narrow the settings displayed, type “other linker flags” into the search box.
  • Edit the “Other Linker Flags” setting and append a space followed by “-all_load -Obj-C” to the end.
  • Open the Finder and navigate to the location of the Cordova Source Code. It is installed at ~\Documents\CordovaLib by default.
  • Drag the “VERSION” file on top of the “Supporting Files” folder in your XCode project.
  • Run your project. You are now compiling the Cordova source code and should be able to set breakpoints within it.


I pieced together the instructions above with help from these pages:

How to Use Cordova as a Component

How to Add PhoneGap Sources to an Xcode Project  This thread helped greatly but gave some misleading instructions. I suspect the web page these posts referenced was updated later. It appears the instruction numbers referenced in the posts have changed.



  1. Collin Forrester says:

    A step that was missing for me was adding $(CORDOVALIB)/Classes to the Header Search Path under Build Phases (also marking it to recursively search). Other than that, great write up!

  2. Perfect… worked perfect with 1.9.0. Thanks 🙂