PhoneGap Lessons Learned- Mac edition

In the last week I’ve learned quite a bit about using PhoneGap-Android with Eclipse on Mac and Windows. Earlier this month I spent alot of time using the iUI library with PhoneGap to make stand-alone iPhone apps from HTML. I thought I’d share my experiences. I’ll begin with using the Mac with PhoneGap for Android. Future posts will address Mac set-up of PhoneGap for iPhone, Eclipse set-up, and Windows set-up of PhoneGap for Android.

First lesson— update PhoneGap early and often. Learn to use git, learn how to use PhoneGap utils to update existing projects and check PhoneGap documentation. It has changed dramatically since last March when I first experimented with it, especially on the Eclipse + Android SDK side. I went down quite a few dead-end paths based on old assumptions and some seemingly helpful blog posts I found from last summer. Please apply my lesson and double check the docs if any of my “tips” below don’t seem to work for you.

Second lesson– Make sure the user you are signed in as has administrative permissions. If you’re unsure, launch the Settings application, look in the System category and open the settings panel for Accounts. Make sure the box is checked for “Allow user to administer this computer”. Don’t worry, you can turn it off after you’ve done the setup. As a little security step, I rarely run as Admin on my own computer.

Basic Setup
Git- Your installation will begin by getting git if you don’t already have it. On Mac the easiest way is to download and run the installer from:
https://code.google.com/p/git-osx-installer/

PhoneGap Repositories- Next, I cloned some repositories from the phonegap repository on github to my Mac Home directory. With git already installed this is as easy as starting Terminal.app and immediately entering:

git clone https://github.com/phonegap/phonegap-iphone.git

git clone https://github.com/phonegap/phonegap-android.git

Those two commands will copy down the latest PhoneGap iPhone and Android frameworks, respectively. Note: As a convenience, we’re getting the iPhone repo while we’re at it, even though it won’t be used in this post. Watch for a future post on “PhoneGap for iPhone – Basic Xcode Setup.”

Environment variables for paths- Since Terminal is running, we’ll skip ahead and add some path information to the shell environment. These updates are only needed for the Android and PhoneGap-Android toolchain. Again, in Terminal, enter:

open .profile

In the resulting editor window, add the following lines to the .profile file.

# add Android_Home for Eclipse builds
export ANDROID_HOME=$HOME/android-sdk-mac_86
# add tools directory for shell access to SDK tools
export PATH=$PATH:$ANDROID_HOME/tools

# add PhoneGap bin for shell access to PhoneGap tools
export PATH=$PATH:$HOME/phonegap-android/bin

Save the .profile file. Close the editor. Quit Terminal. [Really do quit Terminal, because that will help ensure the .profile changes are applied when we get to testing things below.

Android SDK for Mac- Download the Android SDK for Mac from here:
http://developer.android.com/sdk/

Unzip the downloaded archive and move the whole android-sdk-mac_86 folder to your home folder. There should now be a folder named android-sdk-mac_86 at the root level of your home folder. [There are more Android SDK setup instructions found at http://developer.android.com/sdk/installing.html if you need them.]

Test your basic PhoneGap setup- We can test the basics now, without even installing Eclipse and the ADT (Android Developer Tools) Plugin or using Xcode.

First we’ll test the PhoneGap Android command tools by creating mysample as a sample project. Open the Terminal again. Enter:

droidgap gen mysample

NOTE: Don’t get fancy and use a different name for testing. I found out the hard way that you’ll get ruby script errors if the name includes a hyphen. I suspect spaces and other special characters may also wreak havoc with PhoneGap ruby scripts.

It will take a minute to do its work. If all worked well, it should have made a new sub-directory named mysample inside of your Home directory. Verify this by looking in Finder or typing ls in Terminal and looking for mysample in the list of files.

Debugging PhoneGap Android command tools- If it didn’t work, then some likely possibilities are that something got copied to the wrong place or an environment variable (a path) was set wrong. Make sure your Home folder contains the following folders:

android-sdk-mac_86
phonegap-android
phonegap-iphone

Check your paths by examining the current value environment variables. To do this, enter the following in Terminal:

set

Scan the output and make sure the line with PATH= includes something like:
/Users/yourUserName/phonegap-android/bin

Edit .profile again or move folders if necessary. Quit Terminal, re-open it and try again. That’s about the best help I can offer, other than the PhoneGap Android docs.

Test your basic Android SDK setup- Now we can try the Android SDK. Again, in Terminal, enter:

android

If all goes well in a few moments you should see a window that looks like the small thumbnail below, and you can continue on to Install Android SDK Packages.

Debugging Android SDK Basic Setup- You should know the drill by now; check the folder structure and names and check the environment variables. In this case the key folder is android-sdk-mac_86 and the corresponding environment variable is ANDROID_HOME which should contain something like:
/Users/yourUserName/android-sdk-mac_86

Install Android SDK Packages- In the Android SDK and AVD Manager Window (shown above), scan the list in the left column and select Available packages. Check the box next to Android Repository and also check the box next to Third party Add-ons.

At this point, I was tempted to be conservative and download the bare minimum. It turns out better if you just downloading everything. That way you can easily publish for a broad range of Android devices by having the most basic and the most current APIs available.

With everything checked, click on the button for Install Selected. It may take awhile.

If you’ve got this far you’ve got all the basics and are ready to proceed to Eclipse or get started with PhoneGap for iPhone with Xcode. Both of those are separate posts though.

If you want to jump ahead, you can make use of the Android Developers Installing the SDK instructions. That will help you with installing Eclipse and the ADT (Android Developer Tools) for Eclipse.

Keep in mind that you have already completed their steps #2 (Downloading SDK) and #4 (Adding Platforms and Other Components).

3 thoughts on “PhoneGap Lessons Learned- Mac edition

  1. Thanks for the tips and sharing Tom! I can totally relate on the updates for phonegap. I’ve been tinkering w/ iphone OS using phonegap, but really appreciate the tips for Android. Curious why you are using iUI? It was one of the first frameworks and seemed to be to dated/limited for me. I’ve found that iWebkit has the most potential to support older mobile browsers. For newer browsers, jQuerymobile.com seems most promising, but still in ALPHA.

    1. Jason, I used iUI because I learned it in late 2008 and already knew it.

      Funny that you mention jQuery mobile, I begin porting my prototype to that on Monday.

Comments are closed.