PhoneGap Lessons Learned- Windows Edition

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:

  1. 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.)
  2. Apache ANT (Instructions aren’t too clear, I just downloaded and unzipped to c:\android-sdk-windows)
  3. 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.)
  4. Git (msysgit)
    (Here I felt comfortable getting the latest, 1.7.3.1, since it is not directly in the build process.)
  5. Android SDK
  6. Eclipse IDE for Java Developers* (Eclipse ‘Helios’ version 3.6.1 worked well for me)
  7. 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).
  8. ADT (Android Developer Tools) Plugin for Eclipse
  9. PhoneGap-Android (Long term you’ll be better off cloning via git instead of downloading. Later instructions help with using git clone…)

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 phonegap‑android directory.

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,

  1. When running the Android SDK installer, change the install folder to:

    C:\android-sdk-windows

  2. Extract or move the Apache ANT directory to the root (e.g., c:\apache-ant-1.8.1)
  3. Change to the root of the C: drive when you are ready to:

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

  4. 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 ‘\’).
  5. 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:

  1. Launch Eclipse
  2. Use the Eclipse drop-down menu for Help to pick Install New Software…
  3. In the dialog for “Install” use the drop-down list to select “Helios – http://download.eclipse.org/releases/helios”. Then scroll down to “Web, XML, and Java EE Development”. Expand that item and then check the boxes to add at least Eclipse Web Developer Tools, Eclipse Web Developer Tools, Eclipse XML Editors and Tools, and Javascript Development Tools. The image below may help.
    Eclipse Install New Software dialog
  4. Select “Next” and continue on, accepting the agreements (if you agree).
  5. 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.
    Environment variables dialog
  • The following User Environment variables should be set (example values from my machine)

    ANDROID_HOME=C:\android-sdk-windows
    ANT_HOME=C:\apache-ant-1.8.1
    JAVA_HOME=C:\Program Files\Java\jdk1.6.0_23

  • Verify that the System Environment Variable PATH somewhere contains an excerpt like:

    C:\Ruby191\bin;C:\apache-ant-1.8.1\bin;C:\Program Files\Java\jdk1.6.0_23\bin

  • TIP: As a convenience, append the following to the end of the System Environment Variable PATH

    C:\android-sdk-windows;C:\android-sdk-windows\tools;

    followed by

    C:\phonegap-android;C:\phonegap-android\bin

    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 more causes 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:

HTTP_PROXY=proxyserver.com:portnum
HTTPS_PROXY=proxyserver.com:portnum

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.

UPDATE:

  1. Errors in Tip about PATH. I left some elements out in the PATH tip 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.
  2. Proxy settings. Earlier today I was able to get Eclipse to work just fine with the HTTP_PROXY environment 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.

8 thoughts on “PhoneGap Lessons Learned- Windows Edition

  1. You should also take a look at Titanium from Appcelerator. I have built applications with both (on a Mac, mind you), but I found Titanium to be much easier to deal with, more polished, more built-ins examples/widgets, etc. The downside, is that it’s not really just HTML/CSS/JS, but it’s super easy and runs much faster. If you can code Javascript, you can build a Titianium app quickly.

  2. Impressed with anyone who gets this to work on Windows. Have bookmarked this for when i next try

    I tried it a few months back and gave up, horrible process. Potentially a great technology and works great with XCode

    Someone like Adobe should build a cross platform program that does the same without all the nightmares.

    1. I agree, it worked great with Xcode. Likewise, I agree with Zachary below; once it is dialed in, it seems to just work. Updating your Android and Xcode projects to latest PhoneGap frameworks works well too.

      Interesting comment about Adobe. Yesterday, I mentioned to someone that PhoneGap is to HTML/JavaScript as Adobe AIR is to Flash/ActionScript— a cross-platform wrapper/extender that provides consistency and more access to OS capabilities than the “un- wrapped/extended” source.

  3. Nice writeup. My experience was very similar. Now that I have PG setup, it is very easy to use. PhoneGap might make some more progress if they could somehow make an setup process that doesn’t take a new developer 20 hours to setup and configure to test it out the first time.

  4. You know that ruby isn’t needed anymore?
    There is a java version of the ruby in the phonegap folder.

    Also take in mind, you that the andoid plugin for eclipse will bug the BB plugin (if you would want to use it).
    Also if you want to test on a device i recomend installing HTC sync (if debugging on a HTC device that is).
    Also, a lot of installation will bugg if you don’t have a global variable called:
    ANDROID_SDK_HOME = %ANDROID_SDK%

    Just a heads up and a tip for other developers.

    1. I’d beg to differ on ruby, but maybe you can enlighten me. Ruby not needed for what, just compile? It seems integral to the droidgap commands.

      How does one do droidgap update to update a project to the latest framework? The droidgap.bat/ file contains the following:
      ruby %~dp0droidgap %1 %2
      and that does indeed seem to depend on ruby and not the included file
      phonegap-android\lib\jruby-complete-1.4.0RC1.jar

      Maybe there is a way to do this from within Eclipse?

      Good tip on the Android environment var, it now looks like a best practice might be along the lines of setting three variables for the Android "home" path for the various IDEs. I say this based on PhoneGap docs, your comment, and notes on Appcelerator Titanium and Android SDK Tools r8. I'm updating my system to:

      ANDROID_SDK=C:\android-sdk-windows
      ANDROID_HOME=%ANDROID_SDK%
      ANDROID_SDK_HOME=%ANDROID_SDK%

      Just another heads-up to others who may use multiple Android development tools.

      I'm going to use a similar pattern for bash shell environment vars on the Mac too. Over there it will be:

      export ANDROID_SDK=$HOME/android-sdk-mac_86
      export ANDROID_HOME=$ANDROID_SDK
      export ANDROID_SDK_HOME=$ANDROID_SDK

      I'm avoiding BlackBerry development for as long as possible-- to me, everything pre-BB 5.0 was more hassle than it was worth. (See John Resig comments on slide #28 here- http://www.slideshare.net/jeresig/testing-mobile-javascript.) I might consider some future version or the Playbook stuff.

Comments are closed.