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.
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:
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:
In the resulting editor window, add the following lines to the
# add Android_Home for Eclipse builds
# add tools directory for shell access to SDK tools
# add PhoneGap bin for shell access to PhoneGap tools
.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:
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:
Check your paths by examining the current value environment variables. To do this, enter the following in Terminal:
Scan the output and make sure the line with
PATH= includes something like:
.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:
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:
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).