Introduction
The iPhone Debug Consle is meant to give greater visibility and interactivity on your iPhone/iPod Touch while doing development. I grew frustrated having to go through the "include console.log statement then reload" method of debugging. I wanted something similar to Firebug's fantastic console and debugger.
In trying to find something that would fit my needs, I came across Joe Hewitt's iPhone/Firebug integration, but I wanted something more robust and that worked without firebug and requiring "console.log" in the desktop browser. Since the COMET support in Jetty is quite good, and given that I'm a Java programmer, not a Python one, I decided to just write my own and offer it up to the community. I think it will be helpful to those getting very frustrated with debugging your Ajax apps on the iPhone/iPod Touch.
You can download the latest version, which is considered an Alpha release (even though it's fairly stable). Please log any issues you encounter on the project's Issues page.
Download
iPhoneDebugConsole-0.4a-bin.zip
Screenshots
Installation
1) Unzip the binary package to some location on your hard drive. That's such an obvious step I've always wondered why in the world every OpenSource project includes a bullet similar to this. But there it is. For the sake of completeness, I guess.
2) Open a command line and "cd" into the installation directory (e.g. /home/myuser/iPhoneDebugConsole-0.3a).
3) I haven't got Maven to preserve the executable bit on the "ipd.sh" batch file yet (I'm a relative newcomer to Maven), so for the meantime, you'll need to: (FIXED in 0.4a...you can safely ignore this step now)
chmod +x ipd.sh
4) Then start the console server:
./ipd.sh
OPTIONAL: There is an option you can pass to the ipd console to tell it the port on which you want the COMET server to run. By default it uses 8170. To change it, give ipd.sh the "-P" parameter like so:
./ipd.sh -P 8888
5) Until browsers support cross-domain XHR in a transparent way, you'll need to have the client JavaScript that defines the "ipd.log" function (and the supporting libraries) placed inside the domain you want to access from your iPhone/iPod Touch. I'm really sorry about this, but that's just the breaks at the moment. You might already being using dojo v1.1. If so, then you only need two JavaScript files. If not, then you have to have the ipd-specific client JavaScript files AND the dojo files. A full distribution is included because, as ipd matures, I plan to create widgets for the console application using dijit.
a) To install the ipd files and libraries in Apache, you can either put the following in your httpd.conf file, or in an .htaccess file:Alias /ipd/jslib "/home/myuser/iPhoneDebugConsole-0.1/jslib" Alias /ipd "/home/myuser/iPhoneDebugConsole-0.1/client"Or you could copy the client and jslib directories into your web root at whatever location you desire (just keep jslib/ under wherever you put the ipd.js and _ipd.js). Where the ipd.js file lives is not that important because you're going to tell it what baseUrl to use when you add the script tag to your document.
6) To start using the ipd debug console in your web application, you'll need to tell ipd where you've installed the JavaScript files and then include a script tag that loads a bootstrap file (which loads the actual library files it needs in a script.aculo.us-like way). Somewhere in the head of your document, add two script tags similar to the following:
<script type="text/javascript">
ipdConfig = {
baseUrl: '/ipd/', // trailing slash!
consoleBaseUrl: 'http://192.168.10.1:8170/' // trailing slash!
}
</script>
<script type="text/javascript" src="/ipd/ipd.js"></script>YOU MUST HAVE A TRAILING SLASH! (at least until I've add more checking to account for leaving it off...)
A little explanation:
The configuration parameter ipdConfig.baseUrl should be the same as the Alias you put in your Apache configuration file. In this case, I'm using "/ipd/".
The configuration parameter ipdConfig.consoleBaseUrl should point to the location of the ipd console server you started earlier.
GOTCHA: The hostname and port should be accessible from your iPhone/iPod Touch. This seems like a no-brainer, but trust me, it's easy to forget and leave it at localhost. Since your console server IS NOT running on your iPhone, that ain't gonna work. :)
7) Pull up the url of your ipd console in a browser (tested browsers include Firefox, Safari 3.1, and IE 7...if you use something else, I'd be interested to hear your success or failure). In this case, it is JUST FINE to use "localhost".
http://localhost:8170
8) The console will appear on your screen and it should note that the console service has been started.
9) Pull up your page (in which you've inserted the appropriate code to use the "ipd.log" function, as mentioned in #6) on your iPhone or iPod Touch. On the console screen, it should print out a message that a new client has connected. Every log message is preceded by a USER_AGENT string to help keep things straight. If you see a "New client connected from..." message, then everything is ready to go.
10) To start using it, just insert calls to ipd.log( object || string ) in your JavaScript.
IMPORTANT: You can also send things to the iPhone/iPod Touch to be eval'd there. The text box at the bottom of the console screen is very similar to Firebug's JavaScript console. Type in a command, or even just a variable name, and the results will be logged back to your remote console. You can do things like:
dojo.byId("results").innerHTML = "my html"BE PAITIENT! It might take a second or more to make the round-trip between your desktop and the mobile device. After a slight delay (depending on your latency--whether you're on EDGE or WiFi), you'll see that the "results" DIV has been updated. You can assign variables:
results = dojo.byId("results")And then access them later:
results.style.display
You don't need to call "ipd.log(results.style.display)", as ipd is smart enough to try and log everything it can back to your remote console. If "eval" returns an object, then it will get logged back to your remote console. The command box also supports basic UP and DOWN arrow command history retrieval.
INSTALLATION (source)
ipd uses Maven to build the source code and the distribution files. Command-line version goes something like this:
svn checkout http://iphonedebug.googlecode.com/svn/trunk/ iphonedebug-read-only
then "cd" into that directory and do:
mvn assembly:assembly
This will compile and build distribution packages in the "target/" directory. If you use eclipse and have the Maven plugin installed, then just checkout the source code and import the project into your workspace (there is a .project file already in the root).
README
PROJECT INFO:
Homepage: http://code.google.com/p/iphonedebug/
Issues: http://code.google.com/p/iphonedebug/issues/list
REQUIREMENTS:
Java 1.5 or above.
Bash (for the startup script only). Windows users will need to either use
Cygwin tools (which include bash), wait for me to release a batch file that
does what the bash script does, or write one yourself. Contributions in this
area are MORE THAN WELCOME.
ipd is written in Java, so it support the full range of platforms on which
Java can run. The startup script, however, is a BASH script. That means the
STARTUP SCRIPT will only work on UNIX-like platforms (BSDs, Linux, Solaris,
Mac OS X, etc...).
LICENSING:
1) ipd (iPhone Debug Console) is released under the GNU GPL version 3.
To learn more about this license, visit the Free Software Foundation's
website:
http://www.fsf.org/licensing/licenses/gpl.html
Or read the LICENSE.txt file included in this directory.
2) ipd the Apache-licensed Jetty J2EE server. To learn more, visit
Jetty's website:
http://jetty.mortbay.com/
3) No sense in re-inventing the wheel. ipd uses the great COMETD support
in the dojo toolkit version 1.1. Dojo is GPL-licensed software and you
can find out more from their website:
http://www.dojotoolkit.org/
INSTALLATION (binary package):
1) To install ipd, you need to unzip the binary package to some location on
your hard drive. That's such an obvious step I've always wondered why
in the world every OpenSource project includes a bullet similar to this.
But there it is. For the sake of completeness, I guess.
2) Open a command line and "cd" into the installation directory
(e.g. /home/myuser/iPhoneDebugConsole-0.1).
3) I haven't got Maven to preserve the executable bit on the "ipd.sh"
batch file yet (I'm a relative newcomer to Maven), so for the meantime,
you'll need to:
chmod +x ipd.sh
4) Then start the console server:
./ipd.sh
OPTIONAL: There is an option you can pass to the ipd console to tell it
the port on which you want the COMET server to run. By default
it uses 8170. To change it, give ipd.sh the "-P" parameter like
so:
./ipd.sh -P 8888
5) Until browsers support cross-domain XHR in a transparent way, you'll
need to have the client JavaScript that defines the "ipd.log" function
(and the supporting libraries) placed inside the domain you want to
access from your iPhone/iPod Touch. I'm really sorry about this, but
that's just the breaks at the moment. You might already being using dojo
v1.1. If so, then you only need two JavaScript files. If not, then you
have to have the ipd-specific client JavaScript files AND the dojo files.
A full distribution is included because, as ipd matures, I plan to create
widgets for the console application using dijit.
a) To install the ipd files and libraries in Apache, you can either put
the following in your httpd.conf file, or in an .htaccess file:
Alias /ipd/jslib "/home/myuser/iPhoneDebugConsole-0.1/jslib"
Alias /ipd "/home/myuser/iPhoneDebugConsole-0.1/client"
Or you could copy the above libraries into your web root at
whatever location you desire. Where the ipd.js file lives is not
that important because you're going to tell it what baseUrl to use
when you add the script tag to your document.
6) To start using the ipd debug console in your web application, you'll
need to tell ipd where you've installed the JavaScript files and then
include a script tag that loads a bootstrap file (which loads the
actual library files it needs in a script.aculo.us-like way).
Somewhere in the head of your document, add two script tags similar
to the following:
<script type="text/javascript">
ipdConfig = {
baseUrl: '/ipd/', // trailing slash!
consoleBaseUrl: 'http://192.168.10.1:8170/' // trailing slash!
}
</script>
<script type="text/javascript" src="/ipd/ipd.js"></script>
YOU MUST HAVE A TRAILING SLASH! (at least until I've add more checking
to account for leaving it off...)
A little explanation:
The configuration parameter "ipdConfig.baseUrl" should be the same as
the Alias you put in your Apache configuration file. In this case, I'm
using "/ipd/".
The configuration parameter "ipdConfig.consoleBaseUrl" should point to
the location of the ipd console server you started earlier.
GOTCHA: The hostname and port should be accessible from your
iPhone/iPod Touch. This seems like a no-brainer, but trust me,
it's easy to forget and leave it at localhost. Since your
console server IS NOT running on your iPhone, that ain't gonna
work. :)
7) Pull up the url of your ipd console in a browser (tested browsers
include Firefox, Safari 3.1, and IE 7...if you use something else, I'd
be interested to hear your success or failure). In this case, it is
JUST FINE to use "localhost".
http://localhost:8170
8) The console will appear on your screen and it should note that the
console service has been started.
9) Pull up your page (in which you've inserted the appropriate code to use
the "ipd.log" function, as mentioned in #6) on your iPhone or iPod Touch.
On the console screen, it should print out a message that a new client
has connected. Every log message is preceded by a USER_AGENT string to
help keep things straight. If you see a "New client connected from..."
message, then everything is ready to go.
10) To start using it, just insert calls to ipd.log( object || string ) in
your JavaScript.
IMPORTANT: You can also send things to the iPhone/iPod Touch to be eval'd
there. The text box at the bottom of the console screen is
very similar to Firebug's JavaScript console. Type in a
command, or even just a variable name, and the results will
be logged back to your remote console. You can do things like:
dojo.byId("results").innerHTML = "my html"
BE PAITIENT! It might take a second or more to make the round-
trip between your desktop and the mobile device.
After a slight delay (depending on your latency--whether
you're on EDGE or WiFi), you'll see that the "results" DIV
has been updated. You can assign variables:
results = dojo.byId("results")
And then access them later:
results.style.display
You don't need to call "ipd.log(results.style.display)", as
ipd is smart enough to try and log everything it can back
to your remote console. If "eval" returns an object, then
it will get logged back to your remote console.
The command box also supports basic UP and DOWN arrow
command history retrieval.
INSTALLATION (source):
ipd uses Maven to build the source code and the distribution files. Command-
line version goes something like this:
svn checkout http://iphonedebug.googlecode.com/svn/trunk/ iphonedebug-read-only
then "cd" into that directory and do:
mvn assembly:assembly
This will compile and build distribution packages in the "target/"
directory.
If you use eclipse and have the Maven plugin installed, then just checkout
the source code and import the project into your workspace (there is a
.project file already in the root).
STUFF DOESN'T SHOW UP!:
This might happen if things get out-of-sync between the mobile client, the
COMET server, and the desktop console. Just refresh the page on your
desktop browser and do the same on your iPhone/iPod Touch. If that doesn't
fix it, try issuing a CTRL-C inside the command prompt you used to start
ipd, restart it, then refresh the page in both the console and client.
IMPORTANT: It's best to refresh the DESKTOP CONSOLE first, then the client.
Usually, under normal conditions, it doesn't really matter. The
dojo COMETD implementation is smart enough to reconnect after
the server has gone away and come back, so reloading may not even
be needed in a lot of cases.
I STILL HAVE ISSUES:
This is ALPHA software. It should work fine in most cases, but it might
break at odd times and for no apparent reason. If you can tell what's going
on, then please consider including your suspicions in your bug report.
You can always submit a bug report on the Issues page, whether you're a
JavaScript guru or not:
http://code.google.com/p/iphonedebug/issues/list
