The first lesson learned is that there is a lot of stuff to install to get a Windows machine ready to roll with Eclipse‑Android‑PhoneGap development. Second, I learned it is all really finicky regarding version of Ruby, paths, order of install, etc. Third, I learned that getting a stable setup for this on Windows can take a few hours.
You will need to download and install the following:
- Java JDK (I got the latest Java at the time; Java SE 6 Update 23. Regardless of the version, be sure to Download JDK not the JRE.)
- Apache ANT (Instructions aren’t too clear, I just downloaded and unzipped to c:\android-sdk-windows)
- Ruby ** DO NOT GET THE LATEST RUBY (currently v 1.9.2); get 1.9.1 **
Check PhoneGap docs to see if/when 1.9.2 or later ruby for Windows may work.)
- Git (msysgit)
(Here I felt comfortable getting the latest, 126.96.36.199, since it is not directly in the build process.)
- Android SDK
- Eclipse IDE for Java Developers* (Eclipse ‘Helios’ version 3.6.1 worked well for me)
- Eclipse Web Developer Tools* see paragraph below
(Not mentioned in PhoneGap Docs, but the ADT Plugin has a dependency on the Eclipse Web Developer Tools. Another option is to get Eclipse IDE for Java EE developers which already includes the Web Developer Tools).
- ADT (Android Developer Tools) Plugin for Eclipse
- PhoneGap-Android (Long term you’ll be better off cloning via
gitinstead of downloading. Later instructions help with using
You can dive in and do the installs like I did, using the instructions from Getting started with Android PhoneGap in Eclipse. Note that there are a quite a few potential gotchas. I’ll try to call out some major ones. Some are alluded to above, like “Gotcha #0“— ruby version sensitivity.
Gotcha #1: Order can matter.
Solution: For better results, download and install the the Java JDK first. See gotcha #2 for some tips relating to the Android SDK, Apache ANT, and where you put the
Gotcha #2: Paths (and names) matter, especially if they contain spaces or special characters (or if environment variables have an unneeded trailing ‘\’)
Solution: The PhoneGap wiki mentions the work-around in numerous places, but I found it easiest to install key components to
C:\ (the root) rather than deal with the hassles caused by paths with spaces in the names (ie,
C:\Program Files\…). Thus,
- When running the Android SDK installer, change the install folder to:
- Extract or move the Apache ANT directory to the root (e.g.,
- Change to the root of the C: drive when you are ready to:
git clone https://github.com/phonegap/phonegap-android.git
- Really make sure all the environment variables are set properly— proper names, proper distinctions use of User and System Environment variables, and proper syntax (e.g., no trailing ‘\’).
- When you are ready to
droidgap gen projectname
do NOT use hyphens, spaces or underscores in the project name… weird things will happen as the ruby scripts don’t quote the names and also rely on some implicit naming conventions and use of the underscore.
Gotcha #3: The ADT Plugin requires Eclipse Web Developer Tools, but the basic Eclipse Java IDE doesn’t include those.
Solution: After Eclipse is installed, if you picked the basic Eclipse Java IDE you can add the Web Developer Tools as follows:
- Launch Eclipse
- Use the Eclipse drop-down menu for Help to pick Install New Software…
- Select “Next” and continue on, accepting the agreements (if you agree).
- Be sure to quit and restart Eclipse before Installing the ADT Plugin (see instructions at that link).
Gotcha #4: Environment variables matter. (aka “Gotcha #2 Returns: Paths Redux”)
Solution: Make sure you properly set the necessary environment variables and verify them at the command prompt.
- Set (or do a preliminary verification of) the Environment variables by right-clicking on My Computer and selecting Properties. Then select the Advanced tab and click the Environment Variables button. See image below for an example.
- The following User Environment variables should be set (example values from my machine)
- Verify that the System Environment Variable
PATHsomewhere contains an excerpt like:
- TIP: As a convenience, append the following to the end of the System Environment Variable
Then you will be able to use common Android SDK and phonegap-android commands without concern for the full path or current working directory.
- Open a new command window and confirm the settings. It must be a new window for it to reflect the changes you just made. In the new window enter the following command and press Enter:
set | more
The set command will list the current values of all the environment variables and piping (‘
|‘) the output through
morecauses it to display one screen at a time pausing until you hit the space bar to advance to the next screen. Verify the values again.
- Test your verified setup by entering a phonegap utility command. (NOTE: this assumes you’ve already cloned phonegap-android using git… see Gotcha #5 below). The command below will generate a new project called ‘myproj’.
droidgap gen myproj
You shouldn’t get any errors. If you do verify, versions and paths That’s about the best help I can offer, other than the Getting started with Android-PhoneGap in Eclipse docs.
Gotcha #5: Proxy settings may be needed and seem to conflict. Settings for msysgit aren’t obvious, and seem to interfere with Eclipse proxy settings (creating “msysgit proxy misery“). I discovered this one at the workplace yesterday, where using the proxy server is a must.
Solution: The proxy settings for Eclipse are fairly straightforward (eg, use the drop-down menu Window to select Preferences. Then expand the tree control for General and select Network Connections.)
Not-so-obvious are the proxy settings for msysgit, nor is it obvious that they can clash with the Eclipse settings. To set the proxy for msysgit, you use environment variables. I set these using User Environment Variables (see above) and setting the following variables:
Where proxyserver.com is the fully qualified name or IP address of a proxy server and portnum is the active port for said proxy server. After setting those two variables, I was able to successfully clone phonegap-android using this command with the prompt already set to
c:\ as the current directory:
git clone https://github.com/phonegap/phonegap-android.git
Unfortunately, I needed to go back, and “un-set” (delete) the User Environment Variables for the proxies in order for Eclipse to work with updates, installs, etc. In hindsight, I might have been able to leave those environment variables in effect and set Eclipse to connect “Natively” or “Directly” without a proxy, instead of removing the variables and using my Eclipse manual proxy settings.
- Errors in Tip about
PATH. I left some elements out in the
PATHtip above. I updated it and forced a line break for clarity. You may find PhoneGap docs that contradict my tip, but it works well for me as is.
- Proxy settings. Earlier today I was able to get Eclipse to work just fine with the
HTTP_PROXYenvironment variables in place and the Eclipse preference for General > Network set to Active Provider “Manual” with proper proxy server address and port values.
Whew. I’m not going to make this even longer. Much of the rest of the installation and usage is relatively well documented elsewhere.
I’ll watch comments for feedback on this lengthy post. A follow-up post will address turning a generated phonegap-android project into an Eclipse project. In the interim, I’ll likely post something shorter about getting phonegap-iphone going in Xcode.