Installing Weinre remote debugger on the Mac OSX Lion

Weinre, which is short for Web Inspector Remote (pronounced “winery,” “wine-ray,” “whiner,” or “weiner,” depending on your native accent or sense of humor), allows us to debug our mobile app code remotely, that is, in a desktop browser window outside the mobile device. Why would we do this? Because checking our HTML/CSS/Javascript during development in a browser doesn’t necessarily mean it’ll run flawlessly in the target mobile device. The environments are different. Also, 9 times out of 10, the device has poorly integrated debugging of its own.

How steep is the learning curve for this tool? Well, if you are habiitually using Google Chromes’s Javascript Console (in Google Chrome, click on the wrench icon > Tools > Javascript Console), then you’ll quickly grasp this tool (which is WebKit’s Web Inspector), since they are the same tools, with the addition of one extra tab in Weinre for Remote.

Currently, Weinre, developed by Patrick Mueller, only works in Webkit-based browsers like Google and Safari, as used in iPhone and Android devices. Here are the steps to download and install the software tool, and get it running on an iPod touch device running an app which uses Cordova PhoneGap. These steps are extremely thorough, designed for newbies to coding. (You’re welcome.)

(Sept. 21, 2012 update: If you use a Mac, you may want to try the iWebInspector, which is more feature-rich and designed to replace Weinre on the Mac.)

1. Download an “unofficial” binary package of weinre at http://people.apache.org/~pmuellr/weinre/builds/

I chose to click on:
2.0.0-pre-H41DGW8S-incubating/ (29-Jun-2012 14:53)

. . . then clicked on:
apache-cordova-weinre-2.0.0-pre-H41DGW8S-incubating-bin.tar.gz (29-Jun-2012 14:53 2.4M binary archive)

It was put into my Downloads folder at apache-cordova-weinre-2.0.0-pre-H41DGW8S-incubating-bin

2. Go to http://whatismyip.com and note your IP address, which looks something like this:
234.239.123.194

3. Open Textedit and type in the following. In the first line, type in the IP address you received from step 2:

boundHost: [your IP address]
httpPort: 8080
reuseAddr: true
readTimeout: 1
deathTimeout: 5

(These lines are explained at http://people.apache.org/~pmuellr/weinre-docs/latest/Running.html)

4. Save it to the folder in step 1 as server.properties (without the quotes or suffix). Weinre will use these settings when starting up.

5. Double-click on the weinre file in the folder from step 1. A Terminal window will open, showing that the server has been started at http://localhost:8080 (your number might be 8081).

6. Open your Webkit-compatible web browser and copy/paste step 2′s entire localhost URL into the URL field and hit Enter/Return. If the server is running, you’ll see Weinre information.

7. Open your PhoneGap app project’s index.html page and copy/paste (“inject”) the following line just above any the other scripts in the <head> section:

<script src=”http://debug.phonegap.com/target/target-script-min.js#yourAppName123″></script>

You may substitute “yourAppName123″ with your true app name or any other unique string of text (or leave as is – don’t you love freedom of choice?).

8. Also type this sample code just above the </head> tag in the index.html file so we can output some sample content to the Weinre console:

function testingConsole() {
console.log(“Reached end of Body”);
}

. . . and put this code just above the ending </body> tag so we can execute the above code and view it on the Weinre console:

<script type=”text/javascript”>testingConsole();</script>

Save your file.

9. In Xcode, open your app, then open up [app name] > Supporting Files > Cordova.plist. For the ExternalHosts Key, add a new line (click and hold your cursor over the ExternalHosts name, then click on the plus icon that appears), and type in your IP address in the Value field at right for the new row that appears. Leave the Key and middle column entries as is.

10. Attach your device to your Mac and hit Run in Xcode.

11. After the code is running in your device, visit http://debug.phonegap.com/ and type this portion of the script from step 7:

yourAppName123

. . . into the Step 1 field in the browser. You should see the link update with your text substituted. Make sure it matches what you pasted into your index.html file.

12. Now hit the link in Step 3. After a moment, you should see your device info on the screen, showing your IP address and index.html file location on your hard drive. Just above that information appears the Web Inspector tabs: Elements, Resources, Timeline, and Console. Remote is at the far left and is, as mentioned before, unique to Weinre.

13. Click on the Console tab in the browser. The console text from the script in step 8 should appear.

14. Click on Console in the browser, type the following underneath and hit Enter/Return:

alert(“From Weinre to the device!”);

. . . and the alert should display in the device.

9. If you click on the Remote tab, you might find none under Devices. I think this means a timeout has occurred. Merely return to step 11 above and continue.

For security concerns, you should run this only as needed.

If you return to the Remote tab and see an IP address different from yours, I don’t really know what that means, so I recommend shutting down the Terminal app and starting again (step 5 then 10 on).

A little more about Weinre
(from http://people.apache.org/~pmuellr/weinre-docs/latest/Running.html)

When using weinre, there are three programs interacting with each other.

Debug Server
This is the HTTP server that you run from the weinre-node distribution. It’s the HTTP server that’s used by the Debug Client and Debug Target.

Debug Client
This is the Web Inspector user interface; the web page which displays the Elements and Console panels, for instance.

Debug Target
This is your web page that you want to debug. This name (Debug Target) is also used to refer to the machine running the browser displaying the web page. Since a design point of weinre is to allow debugging applications on mobile devices, the debug target, when speaking of the machine, is your mobile device. The Debug Target is the squirrelliest bit. You will need to arrange to inject some JavaScript code, provided by the Debug Server, into your web page, in order for it to function as a Debug Target.

Related links of interest
http://people.apache.org/~pmuellr/weinre/docs/latest/ (weinre home) http://people.apache.org/~pmuellr/weinre/builds/ (downloads)
https://groups.google.com/forum/?fromgroups#!forum/weinre (Weinre Google Groups)

http://muellerware.org/papers/weinre/manual.html
http://jbkflex.wordpress.com/2012/04/12/debug-mobile-web-applications-remotely-with-weinre/
http://techblog.hk.agenda-asia.com/2012/03/07/weinre-remote-debugger-for-mobile-web/
http://hiediutley.com/2011/11/22/debugging-ios-apps-using-safari-web-inspector/
http://www.youtube.com/results?search_query=weinre