Installing PhoneGap 1.0 into Xcode 4 (Mac OS X, Snow Leopard)

PhoneGap allows you to avoid learning Objective-C when making iPhone apps. With PhoneGap, you insert your HTML, CSS, and Javascript in the www/ folder and PhoneGap will make sure it shows up on the screen. (Disclaimer: I know very little Javascript. Much of what are downloaded from the web, then are modified by trial and error to suit my project. I have been a web developer for nearly 20 years.) I am going to assume you don’t know Javascript, and are only barely familiar with Xcode, the software necessary to compile iPhone apps for the App Store.

The Windows PC is my main computer, so I’ll assume you are barely familiar with the Mac interface (maybe you’re moving from the PC to the Mac just for building apps, like me). So I think you’ll find these steps easy to follow. At this time, there are no screen shots (sorry). I assume you already have Xcode 4 installed. I’m not going to go into provisional profiles here; I’m going to assume you will take care of that on your own.

1. Download PhoneGap 1.0 from . I downloaded the zip file, moved the folder to Documents, and renamed the folder phonegap-1.0.

2. Launch for the next step to create/extract some files. (To launch Terminal, click on magnifying glass in upper right of desktop screen and type in Terminal. Click on the Terminal name in the results box to open.)

3. Type in Terminal:


(present working directory) and hit enter to get your present folder. It should be your Home folder.

4. Type:

cd Documents/phonegap-1.0

(or wherever you put your folder) and hit enter to get to the “makefile” folder.

5. Type:


and hit enter.

Wait a few minutes as Terminal builds the PhoneGap framework used in Xcode 4.

6. Exit Terminal when the last line ends with your home folder name.


1. Start Xcode 4 and select the option to start new project.

2. Under iOS > Application, select “PhoneGap-based Application” and click on Next.

3. Add Product Name (the final name of your application with no spaces allowed – mine was LearnItalicCalligraphy) and Company Identifier (com.yourcompanyname). Click on Next.

4. Select folder location where the project will be saved.

5. Perform a Product > Build. This creates a www folder in the Finder, which you will navigate to next.

5. Right-click on the project name in the blue bar containing the project name in the far left window and click on Show in finder.

6. In Finder, you should see the www directory beside your project. Drag the www from the Finder into Xcode 4 onto the project name with the blue bar. Do NOT check the box to “Copy the items into destination group’s folder.” Select radio button for “Create folder references for any added folders.” The www folder, once installed, should be blue, not yellow. If it is yellow, delete it and carefully follow step again, and select the proper radio button in the dialog box. In the dialog box, the project name should be checked.

There are other steps to take if you are using Xcode 3, but we are not covering that aspect in these instructions.

7. Run Xcode in the simulator to test. An HTML page should display.

8. You should see a PhoneGap link on that page. Click on it and check your console log for any white-list rejection errors. (When I tapped on the link to PhoneGap on the simulator, I received:
ERROR whitelist rejection: url=’′.

9. Add your allowed hosts in Supporting Files/PhoneGap.plist under ExternalHosts (wildcards OK). I added* to the plist, and the error above did not re-occur after I did a Run in my device. (To do this step, click on Supporting Files > PhoneGap.plist, then on the gray triangle to the left of ExternalHosts, then on the + sign and type the text in the far right field. Then tap outside the field and save the changes by File/Save.)

However, the web page opened in a new screen, and there was no way to get back to the app from there. One would need to turn off the device and turn it on again to get the app to open again. So we need to install the ChildBrowser plugin to rectify this (detailed in another post). Also, when a link goes to an external host, the screen is not resizable; the website extends past the screen.

10. Drag or copy all the HTML, CSS, and JS contents of your project into the “www” folder in the Finder window, NOT into Xcode.

11. Run Product > Clean, then Run Xcode in the simulator to test. Test the external URLs and check for any whitelist errors, and fix.

I added* to PhoneGap.plist for my external link videos. Clicking on a YouTube link yields the error:
2011-09-19 11:32:51.714 AppTesting11[1426:707] Failed to load webpage with error: Frame load interrupted.
When I changed the URL from:


and added* to the plist, the video played in the browser specially sized to fit the mobile screen.

Further Xcode 4 setup for iPhone settings (all the following steps occur within Xcode)

1. Click on the Supporting Files folder in the left folders pane and click on YourProjectName.plist and update the com.companyname.appname Bundle Identifier with the information you submitted when you made your Provisioning Profile. (For coding newcomers: “YourProjectName” will have your own project’s name.)

1a. In YourProjectName.plist, change the Bundle display name for the name you want under the icon on the home screen. Keep it short and remember to test it later in your device. Titles of 11 or fewer characters work best. Titles too long will truncate and end with ellipses (. . .), which look poor!

1b. In YourProjectName.plist, hold the cursor over an entry in the Key column until the + and – buttons appear, and click on the + button to add a property. Choose the “Icon already includes gloss effects”, and “YES” if you don’t want Xcode to add the gloss effect to the app icon that will appear on the device’s home screen. Select “NO” (default) if you want Apple to add the gloss to top of icon.

1c. Before leaving this page, save.

2. At the top of the left folder pane, click on the blue heading showing your project name. You now see three panes. In the middle pane, click on the Target name. Under the Summary tab, make changes where necessary, such as Version number (1.0), Devices supported, and Deployment target. It’s important to select a deployment target that your code supports AND (for testing purposes) the earliest one your device includes. I chose 4.0. Also click on the Supported Device Orientations you want your device to support. Don’t worry about the Main Interface. Lastly, if you have supplied the icons for the project, they should appear in the App Icons section. If one is missing, you’ll see that, too. More about icons later.

2a. Under Build Settings tab, Architectures heading, select your Base SDK to reflect the latest iOS installed on your computer. In my case (as of Sept. 2011), it’s iOS 4.3.

2b. Under Build Settings tab, Code Signing heading, Debug setting, make sure the iPhone Developer setting is current if you want to test in your device. For the Release setting, choose the Distribution profile. These would have been created online, downloaded, and installed previously. Yo can save this step for later, when you are ready to upload to Apple.

2c. Under Build Settings tab, Deployment heading, select the iOS Deployment Target your code will support, AND if you can test it on a device containing that version.

2d. In the middle pane, click on the Project name (above the Target name). You will repeat the above steps with the same settings. Many errors arise from entering the information only once – the information has to be entered twice.

2e. Under Build Settings tab, Architectures heading, select your Base SDK to reflect the latest iOS installed on your computer.

2f. Under Build Settings tab, Code Signing heading, Debug setting, make sure the iPhone Developer setting matches your project name if you want to test in your device. Choose your Distributor profile for the Release setting if you have one already.

2g. Under Build Settings tab, Deployment heading, select the same iOS Deployment Target.

3. Still in Xcode 4, click on the Resources folder at left. Replace the splash and icon images with your own. Pixel sizes of each (right-click on the folder and select to “Add files to . . .” the project):

icon-72.png = 72 x 72px
icon.png = 57 x 57px
icon@2x.png = 114 x 114px

Default.png = 320 x 480px
Default@2x.png = 640 x 960px
Default-Portrait.png = 768 x 1024px
Default-Landscape.png = 1004 x 768px)

We still need to install the ChildBrowser plugin so that we’ll be able to return to our app after clicking on an external link. Follow the steps in that post.

Do File > Create Snapshot of your current working project before the next steps so you can revert if necessary. A Snapshot is a copy of the project stored away. You can delete these snapshots by going to Window > Organizer, click on Projects at top, then on the project name at left. After clicking on a Snapshot, click on the Delete icon at lower right.

If you need to revert the project, you will first create a new folder in Finder, then click on the Restore Snapshot icon to save it to that folder. You’ll have two versions of the project; the reverted version will not overwrite the previous version.

Installing ChildBrowser

Installing data persistence with local storage

2 thoughts on “Installing PhoneGap 1.0 into Xcode 4 (Mac OS X, Snow Leopard)

  1. Not going to lie, This Article saved me, even though a bit outdated! I am a college student working on a project and it has become hell. Thanks to you I have finally ended the terror! Sincerely, a Finance Major….

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s