PhoneGap – The missing android/windows setup guide
The Introduction
Yesterday I spent a good part of the day setting up the absolutely fantastic framework PhoneGap. If you don't know what PhoneGap is, and you are a web developer, you are truly missing out. The only thing I can compare it to (from a high level) is Adobe Air. Air lets you build a page out of html, css, and js and then renders it in a webkit self-contained browser that you can then package up and distribute on any platform that runs air (Win/Mac/Linux), and yes you can also build Air apps with Flex and Flash. PhoneGap is similar to Air as it too uses html, css, and js to build apps for Android, iOS, WebOS, Blackberry, Symbian, and Nokia.
Now don't let my title fool you, there is a guide (and a pretty good one at that) waiting for you in the PhoneGap Wiki, the problem is that it is now out of date and will cause you grief if you try to follow a few of the steps because they look like they are the right steps to follow. That's why I've created this entry to walk you through the mistakes I blundered through to get it set up and working on my Windows 7 box (My mac died, and my linux lappy is a netbook - not ideal for developing on... plausible, but not ideal).
The Installation
If you point your browser toward phonegap.com you can grab the latest version of PhoneGap that is ready for the taking (note that the big download button in the top right will give you the master package, that is to say that you'll get compiled versions of phone-gap for all devices. If you GIT in, you can pick up just the resources for the device you want to develop for). Also you should notice a large 'Get Started' button (click that open in a new tab).
Starting on the 'Get Started' page, go ahead and click on the 'Android (Eclipse)' link. This will drop you in the wiki for setting up Android development with PhoneGap. Please note that I am writing this for version 0.9.1, so by the time you find and read this, my guide may be well out of date. Lets follow the listed steps (with my commentary)
- Install JDK 1.6 - Yep, totally accurate and awesome, do NOT download the JRE, make sure you get the JDK (you may also need to set up a JAVA_HOME system or user variable).
- Install Eclipse - This one is wicked straight forward. Just about any 'brand' of eclipse will do, if you can hit the update site to install ADT, you can use that version of eclipse. For the fun of it I even managed to install ADT into IBM Rational Application Developer, but you may want to stick with the vanilla Galileo version of eclipse.
- Install the Android SDK - Another fairly straight forward piece. Download the SDK, unpack it (to root), then open it and update any of the pieces you need (in my case, everything). Once you are finished, make sure you've added the SDK to your PATH, and crack open your freshly installed eclipse and install the ADT.
- Install Apache ANT - Go and grab the latest binary of Apache Ant. After grabbing the zip, uncompress it somewhere (root sounds good), and add that path (I used the bin folder instead of the unpacked root) to your system PATH.
- Install Ruby - This step was my first hang-up. Since I am not a Ruby programmer, and where I work refers to Ruby as the devil, I have had no previous interaction with Ruby. So do NOT follow the original Ruby download link, instead head over to the RubyInstaller. This will install Ruby into your system without having to grab extra dependencies and monkey with your path (it contains a code monkey that does that for you 
). After you have installed Ruby, you are ready to attempt to install nokogiri. Since I had never used Ruby and only knew of it as a mystical scripting language that does... uh... well... you can build things with it. I had no idea what the line "install nokogiri via - gem install nokogiri' meant. So I cracked open my command line and typed 'install nokogiri via - gem install nokogiri', and of course nothing happened. What you really need to type is just:
gem install nokogiri
then wait 5-10 minutes as nokogiri is downloaded and installed (there I just saved you an hour of changing your PATH, cracking open .bat files and trying to ascertain what they are doing, and surfing Google to figure out why there doesn't seem to be an 'install' or 'via' command in ruby).
-Install Git - There are plenty of ways to install git, you can use Cygwin (blech), or you can grab the nice msysgit program. Keep in mind that msysgit is in preview, so don't expect a fully-functioning, never-crashing, awesome piece of awesomnicity. But it does work, and I'm a fan of it. After you get msysgit installed, remember to generate an SSH keypair! When following the SSH keypair link, don't attempt it in command prompt, crack open 'Git Bash' from your start menu.
- Whew! Almost there! all that's left is to make sure you installed ADT and the Android SDK correctly, so follow the hello world from either a book, online tutorial, or the official hello world from Google.
- Ok, here's the second hang up, and quite the massive hang up it is. The directions here say that you need to either roll with step 10a, or 10b. 10b says that it is the 'old way' and is what comes bundled in the "read me" for PhoneGap 0.9.1. 10a is an exercise in futility that will get you giving up and playing "The Force Unleashed" for 2 hours while you cool down by throwing storm troopers against the wall and stabbing the ones that lived with your light-saber. So just to be clear... SKIP 10A!
Lets do this instead, get your resources put into a folder, say "C:\www ". Make sure you include your icon.png file (if you don't have one, borrow the one bundled with PhoneGap - phonegap/framework/res/drawable/icon.png). For testing purposes, I copied the files from my phonegap/example folder to C:\www (index.html, master.css, and phonegap.js). Now lets follow the readme and run:
ruby ./droidgap \\android-sdk-windows TestGap TestGap.com C:\\www C:\\phonegap\projects\TestGap
- Note that the double back-slashes were used because I'm running Windows 7 on my development box, if you are running a different version of windows, using the double backslashes will probably mess you up.
- If you received a '.' is not recognized as an internal or external command, operable program or batch file. Then you left off "ruby" before "./droidgap". droidgap is a ruby script, and as such must be called from ruby, if you had ruby on and still got that error, then you don't have ruby in your system PATH, add it and try again. If you received any other error, you will need to correct what is broken (missing xml config, bad files, etc).
- Another thing to keep in mind, there are a few places (including the wiki) that will tell you that your local.properties file is hosed, and you'll probably be confused because you DON'T HAVE ONE. Don't worry about it, that is a generated file, it doesn't come pre-packaged, so don't think your download is bad when you unpack the zip and it's not there. When you run the droidgap script it will create one for you (populated off of the values entered when calling that script).
- Lets open your generated project! - Open Eclipse and File -> New -> Project. Then choose Android -> Android Project. Give your project a name, click the radio button for "Create project from existing source", and browse to your generated project folder (if you followed what I typed that would be in C:\phonegap\projects\TestGap). Next choose the API level (for information reguarding API levels, please consult the Android docs), and click OK.
- Note that unless you modified your AndroidManifest.xml file, the default is '2'. My projects (once created inEclipse) threw build errors until I had changed this to a higher level (I don't remember if it was when I switched to 1.6, or 2.1, but I was playing with those two builds). Also remember that if you change the AndroidManifest.xml file, that you'll need to right-click on your project and change the build target to match (well, you don't have too, but you'll get warnings and something that looks like an error but isn't, so I'd say you *should* change the project build target to match).
- Don't forget to add the phonegap.jar to your project. Expand the libs folder and then right-click on phonegap.jar and choose "BuildPath -> Add to Build Path", if you do forget, you'll get project errors and be unable to fix them.
Once you have the project imported/created and you are error-free, launch the app (either through the Android Emulator, or through your android phone/debugging hardware (I'm not providing the steps to setting that up, but if you have debugging hardware, you probably already know how to use it ). I tested both, and while the emulator did load it, since it was an emulator, it didn't really work (hard to test an accelerometer from an emulator). Testing on my HTC Hero though was pure beauty; geo-location worked, the beep button played my notification sound, and the accelerometer was returning good data, it was awesome!
Hopefully this will give you a good head-start into developing with PhoneGap in Windows for Android. PhoneGap is awesome and I hope that it continues to grow, get better, and get used. If you find it helpful, drop them a line, I know personally that they are very fast to contact and good to work with if you run into a problem.
Let me know if this entry needs any fixes, or images/screen captures to help you out with.
Print This Post
February 8th, 2011 - 07:18
@Vinayak
You are welcome, thanks for visiting and commenting. I hope you found the post helpful.
February 23rd, 2011 - 00:33
I’m looking for advanced phone gap developer in Vancouver
if anyone knows anyone interested johnfon at hotmail dot com
March 29th, 2011 - 07:50
Can we get windows environment for developing website for iPhone in PhoneGap?
March 30th, 2011 - 06:43
@Bhavesh
Unfortunately the compilation process that takes your html, js, and css and turns it into an iOS app requires that you compile on OSX (running on an intel-based mac) with Xcode installed.
If requirements ever change they should be posted at http://www.phonegap.com/start.
There is some good news however. Phonegap has a beta program called “Build” that allows you to build your project and upload it to their server and it will kick back your app in whatever flavor you want, android, iOS, blackberry, palm, winphone7, or symbian. The site was down for me today, but you can check the program out by visiting build.phonegap.com. My guess is that during beta this will be free and then switch to a paid per app model (to cover licensing fees etc). Please note that to release an iOS app into the appstore you will need a developer license from Apple.
April 1st, 2011 - 11:16
This might be helpful:
http://wiki.phonegap.com/w/page/38469560/IPhone-Development-with-PhoneGap-and-Windows
April 2nd, 2011 - 06:50
@laker2000
.
Thanks for posting the link. I took the question to mean publishing an iPhone app in a purely windows environment and completely forgot about running OSX in a VM
*Now for the legal disclaimer bit*
We always encourage users to make sure they properly license their software, including copies of OSX.
April 27th, 2011 - 15:08
j’ai un prblème avec droidgap :
no such file or directory ./droidgap (LoadError)
April 27th, 2011 - 18:34
@Jarray
Are you running the droidgap script with the ruby command? Also check to make sure you have ruby in your system path, without it you will get similar errors.
July 7th, 2011 - 14:10
Ok; so where is droidgap again? It does not exist anywhere. I’m on Win7 64bit.
I was reading it comes with PhoneGap – but I am not seeing it.
I’m probably missing something very simple.
July 8th, 2011 - 22:41
@Chris
Sorry for the delay in getting back to you. It’s been a while since I last played with PhoneGap, but depending on where you grabbed the zip file, the droidgap script may not have been included. I would suggest trying to get the source files directly through the git repo and seeing if they are included there.
Also keep in mind that droidgap is a ruby script and must run under your ruby shell (meaning that it will throw errors or claim not to exist from the windows command line shell).
Hope that helps.
July 11th, 2011 - 21:30
Thanks for such a good post!
I had few queries:-
1)WHich platforms can i target for using PhoneGap?
2)PhoneGap is a cross platform development tool for smartphones like Android,Blackberry,Symbian,iPhone etc but what are the different versions of the OS’ on which PG apps wud work.Symbian/Android/iPhone etc are umbrella words but wat are the exact versions or Os on which PhoneGap apps can be run.?
3)Do i need to get different emulators to check the performance of the same app.?
4)If I simply write apps in notepad and upload it on PhoneBuild then would I get the same app as when I would have downloaded PhoneGap and all the OS specific requirements and build it on my computer itself.?
5)Do the apps made in PhoneGap(or via PhoneBuild) have the same extension as those of the native apps?
6)If I dont intend to launch my app in appstore wud i be spared form the cumbersome process of getting licenses or whatever?
7)If PhoneBuild services are already their(no matter in beta) then why are people still taking the pain of setting PhoneGap and other OS specific requirements and not simply uploading thier code on PhoneBuild and getting their apps easily?
8)I guess i m repeating myself but this is really bothering me……..what all phones can I build for…(for instance ..I had a NOKIA 5130 xpressmusic (S60) can i build symbian apps and install it on my mobile)
9)Where can I get a good tutorial on HTML/CSS specifically aimed at building cross platform apps on PhoneGap?
I am very sorry for botheing you but your answers wud directly go on my website and my blogs for everyone to see and make use of.This wud really help and clear the doupts and misconception of all the rookies and beginners out ders…..THANK YOU VERY MUCH..looking forward for your help!
July 11th, 2011 - 23:02
@Rahul
Thanks for dropping by and enjoying the post. I do not have all of the answers you are looking for, but I can try to point you in the right direction or at least give you my opinion.
1) You already named the platforms, and yes it is very generic as you pointed out in your question 2… so let’s move on to that question.
2) Excellent question, unfortunately I can only answer with what I know. Android is supported from version 1.5+, that being said I do not know if Honeycomb is fully supported (I don’t see why it wouldn’t be, but I haven’t tried it). As for iPhone, I’d venture a guess at iOS version 2.0+. Blackberry is supported at least at versions 4.6-6.0 (with varying degrees of hardware support). WebOS, Windows Phone 7, Symbian, and Bada are listed, but with no exact versions listed. You can check out this page to see the list of supported features per OS.
3) Yes, while most mobile devices lean heavily on webkit, nothing ever renders the same across all browsers. It can be as simple as fonts installed on the device to specific tweaks made to the browser by manufacturer etc. Check this post over at Noupe for everything mobile design related (including links to download different emulators)
4) That’s the plan behind PhoneBuild. Write it, upload it, enjoy it on every device. I haven’t tried it, but that’s the general idea.
5) They (the programs/apps) should have the proper extension per OS/Device type (.apk for Android etc) on download/compile.
6) Sort of. You will never escape the iron hand of Apple. To develop you have to have a developer licence or you can’t compile (you can still open xCode and write, but you can’t export the final app). Android is free to let you do what you want. You’ll only need to pay if you want to publish in their market. Amazon has a slightly different set of rules if you wanted to publish there. If you didn’t want to publish but just release your app on your website, you should be free to do that. Keep in mind that your app will usually have a warning attached to it saying that it is an unknown source and may not be safe (similar to the installation message of an unregistered AIR app).
7) The PhoneBuild beta is exactly that a beta. Some people don’t like beta, and as beta you never know when things will change and your app will no longer work. I’m also thinking that the beta program may be difficult to get into (you have to sign up and wait for a code to be emailed to you).
8 ) I don’t have the list of supported devices, I would say that for iPhone, start at iPhone 3+, for Android start with the Nexus or Hero+. My guess for the others is that if they run the overall listed OS, create the app, compile it, and see if it runs. As a counter-point just because I make an app that runs great on an Evo doesn’t mean that it will run at all or even with any speed on a Hero. The hardware is a bottleneck with PhoneGap as it is really building an app that uses a web view (browser) to render your app to the device.
9) I haven’t found a specific tutorial built just for PhoneGap, however the link I listed above over at noupe lists some of the frameworks that PhoneGap recommends for use. PhoneGap recommends using Sencha Touch, jQuery Mobile, and GWT. I’ve used jQuery Mobile on a few other projects and it is a well thought-out fairly simple solution for mobile builds. You can also check the official documents page over at PhoneGap for some other links and ideas.
Hope this helps.
July 12th, 2011 - 04:55
Very HELPFUL!
Hey Phil thanks for replying so quick. Infact i never expected that u would ever reply but its great to find that you are really taking good care of your blog.I really appreciate your elaborate answers and I have just forwarded the link of this page to my developer community.The links that u gave were really helpful and I along with my whole team of webdevelopers read adnd comprehended your entire text.
I would like you to please put some content for PhoneGap beginners because despite being a such good technology which uses existing webtechnologies for cross platform web development, I hardly find grassroot level tutorials and documentation to help one out . If you take up the pain of posting source codes of a couple of simple apps and that are made from phonegap after cumbersome intitial setup then the it would be great because despite what one says its not a cake-walk to shift from webdevelopment into building apps because even thougg PG uses HTML/CSS and javascript it has its own set of standard libraies and device specific syntaxes.Thus if their existed documentation to guide newbies and help in easy transition from being webdeveloper to a cross platform app developer with underming and abstracting the intricasies and complexity of mobile framework then it would be something that a large pool of people like me would love to read and comprehend.
Phil thanks again and I and my whole team in INDIA are really looking forward for your future posts.
July 12th, 2011 - 07:12
@Rahul
Glad I could help you out, I’ll try to write more posts on PhoneGap when I have a little time.
July 16th, 2011 - 08:35
hi phil,
WHAT I WANT TO SHARE>>>>i browsed a couple of websites and learnt that phonegap apps only work on those symbian platforms in which the symbian os version number is 9.4 or beyond.This encompasses a huge range of symbian mobiles right from S60 3rd edition(featurepack2) till whatever has been released till now ie SYMBIAN ANNA.One can see the symbian platforms for which phonegap apps do work on this site http://en.wikipedia.org/wiki/S60_(software_platform) [just look for mobiles that are beyond S60 featurepack1.....and u can build for it].I also learnt that it is not necessary to download the 846 mb S60 SDK for using symbian emulators but one can simply use RDA ie Remote Device Access which is a free Nokia Developer online tool where one can use all S60{os 9.4+} emulators.http://www.developer.nokia.com/Devices/Remote_device_access/
WHAT I WANT KNOW?>>>>
1)In symbian development do we only build apps with “.wgz” extension and not “.sisx” or “.sis”?
2)I tried to install the demo symbian app that i developed with “phonegap build” using the git repository mentioned on phonegap website http://github.com/wildabeast/phonegap-demo on NOKIA 5800 but it gave an error “FATAL error Kerrcorrupt”.I dont understand i downloaded the symbian app with .wgz extension from “phonegap build” but couldnt get it installed on any S60 device.What should I do?
Phil I dont no much about phonegap but i am trying to comprehend each and every aspect of it ..Your help can prove very vital!!THANKS
July 17th, 2011 - 18:02
@Rahul
Thanks for sharing what you learned about Symbian develpoment and links.
As for your questions I do not have an answer. I do not work for PhoneGap and when I was using it I was developing for Android. The only recommendation I can give to you is to try searching/asking in the PhoneGap Google Group, hopefully someone there has run into your problem and has a quick solution for you.