Running.html - cordova-weinre - Git at Google

 <!doctype html>

 <!--
  * weinre is available under *either* the terms of the modified BSD license *or* the
  * MIT License (2008). See http://opensource.org/licenses/alphabetical for full text.
  *
  * Copyright (c) 2010, 2011 IBM Corporation
 -->

 <html>
 <head>
 <title>weinre - Running</title>
 <link rel="stylesheet" href="css/main.css" type="text/css">
 <link rel="shortcut icon" href="images/weinre-icon-64x64.png" />
 <script src="scripts/main.js"></script>
 <script type="text/javascript">

   var _gaq = _gaq || [];
   _gaq.push(['_setAccount', 'UA-736164-7']);
   _gaq.push(['_trackPageview']);

   (function() {
     var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
     ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
     var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
   })();

 </script>
 </head>

 <body>

 <a class="no-decoration" href="https://github.com/phonegap/weinre"><div class="ribbon">Fork weinre on GitHub</div></a>

 <!-- ======================================================================= -->
 <h1 class="page-title">weinre - Running</h1>

 <div class="toc">
   <a href="Home.html">Home</a>
 - <a href="TestDrive.html">Test Drive</a>
 - <a href="Installing.html">Installing</a>
 - <a href="Running.html">Running</a>
 - <a href="MultiUser.html">Multi-User</a>
 - <a href="Security.html">Security</a>
 - <a href="Building.html">Building</a>
 - <a href="ChangeLog.html">ChangeLog</a>
 - <a href="License.html">License</a>
 <p>
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 </div>

 <!--
  * weinre is available under *either* the terms of the modified BSD license *or* the
  * MIT License (2008). See http://opensource.org/licenses/alphabetical for full text.
  *
  * Copyright (c) 2010, 2011 IBM Corporation
 -->

 <p>This page describes how to use <span class="weinre">weinre</span> to debug
 your own web pages on a remote device.

 <p>First, some background.

 <!-- ======================================================== -->
 <h2>Terminology</h2>

 <p>When using <span class="weinre">weinre</span>, there are three programs interacting with
 each other.

 <dl class="spaced">

 <dt>Debug Server
 <dd>This is the HTTP server that you run from the <tt>weinre.jar</tt> file
 or the Mac application.  It's the HTTP server that's used by the
 <b>Debug Client</b> and <b>Debug Target</b>.

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

 <dt>Debug Target
 <dd>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 <span class="weinre">weinre</span> is to allow
 debugging applications on mobile devices, the debug
 target, when speaking of the machine, is your mobile
 device.

 </dl>

 <p>Both the <b>Debug Client</b> and the <b>Debug Target</b> communicate to
 the <b>Debug Server</b> via HTTP using <tt>XMLHttpRequest</tt> (XHR).

 <p>Typically, you run both the <b>Debug Client</b> and the <b>Debug Server</b>
 on your desktop/laptop, and the <b>Debug Target</b> on your mobile device.

 <p>When using the Mac application, the
 <b>Debug Client</b> and <b>Debug Server</b> are running
 in the same process.
 When you launch the application,
 the server starts, and then the browser included in the
 application is launched
 on the appropriate URL automagically.

 <p>When using the <tt>weinre.jar</tt> program instead
 of the Mac application, only the <b>Debug Server</b>
 is started.  You will need to launch the <b>Debug Client</b>
 in a web browser.

 <p>The <b>Debug Target</b> is the squirrelliest bit.  You
 will need to arrange to inject some JavaScript code, provided
 by the <b>Debug Server</b>, into your web page, in order for it
 to function as a <b>Debug Target</b>.

 <!-- ======================================================== -->
 <h2>Starting the debug server</h2>

 <p>There are two ways to run the <span class="weinre">weinre</span> debug server:

 <ul>
 <li>Running the debug server using the weinre.jar file
 <li>Running the debug server using the Mac application
 </ul>

 <!-- ======================================================== -->
 <h2>Running the debug server using the weinre.jar file</h2>

 <p>To run <span class="weinre">weinre</span> from the jar file,
 execute the following command:

 <pre>
 java -jar path/to/weinre.jar [options]
 </pre>

 <p>Options available are:

 <ul class="spaced no-bullet">

 <li><tt>--help</tt> (or <tt>-?</tt> or <tt>-h</tt>)
 <div class="indent">
 <p>Display this help.
 </div>

 <li><tt>--httpPort [portNumber]</tt>
 <div class="indent">
 <p>The port to run the HTTP server on.
 <p>Default: <tt>8080</tt>
 </div>

 <li><tt>--boundHost [hostname | ip address | -all-]</tt>
 <div class="indent">
 <p>The ip address to bind the server to.
 <p>Default: <tt>localhost</tt>

 <p>With the default of <tt>localhost</tt>, you won't be able to access
 the server from any machine other than the one the server is running on.  You will
 need to bind to another hostname / ip address to make the server accessible to other
 machines.  You can use the value <tt>-all-</tt> to indicate that you
 want to bind to all interfaces available on the current machine.

 <p>Use <tt>ifconfig</tt> on Linux or the Mac, and <tt>ipconfig</tt>
 on Windows, to get the ip addresses available on your machine.
 </div>

 <li><tt>--verbose [true | false]</tt>
 <div class="indent">
 <p>Causes jibberish to be written to stdout
 <p>Default: <tt>false</tt>
 </div>

 <li><tt>--reuseAddr [true | false]</tt>
 <div class="indent">
 <p>Sets the "reuseAddr" flag for Jetty.
 <p>Default: <tt>false</tt>

 <p>May be needed if you restart your server frequently.
 </div>

 <li><tt>--readTimeout [seconds]</tt>
 <div class="indent">
 <p>The number of seconds the server will wait for a message
 to be available to send to the target or client.
 <p>Default: <tt>5</tt>

 <p>Can probably be set larger, but then your browser may
 time out.  Probably don't want to set it much lower than
 this as it will cause additional network traffic when
 no messages are being sent (it will cause more "empty"
 messages to be sent).
 </div>

 <li><tt>--deathTimeout [seconds]</tt>
 <div class="indent">
 <p>The number of seconds to wait to hear back from a
 debug client or target before declaring them dead.
 <p>Default: <tt>3 * readTimeout</tt>

 <p>Normally the default will be fine.  However, if
 you're debugging <span class="weinre">weinre</span> itself, you may wish to set
 it much longer.
 </div>

 </ul>

 <p>You may also create a file named
 <tt>server.properties</tt> in the
 directory <tt>.weinre</tt> in your
 home directory (eg.
 <tt>~/.weinre/server.properties</tt>).
 The keys should be
 the same as the name of the options above,
 with the same values.

 <p>As an example, your <tt>~/.weinre/server.properties</tt>
 file might look like this:

 <pre>
 boundHost:    -all-
 httpPort:     8081
 reuseAddr:    true
 readTimeout:  1
 deathTimeout: 5
 </pre>

 <p>Command-line options override the options specified in the
 <tt>~/.weinre/server.properties</tt> file.

 <p>The server will run until you kill it.  Control-C will do the job.

 <!-- ======================================================== -->
 <h2>Running the debug server using the Mac application</h2>

 <p>Go back and read the description above about the weinre.jar settings.

 <p>Only the <tt>~/.weinre/server.properties</tt>
 file is available to configure the server, as there is no
 traditional command line used to launch Mac "applications".

 <p>The server will run until you quit the application.

 <p>Since there is no practical way to see the stdout and stdin
 from the server when running a Mac application, these streams
 are intercepted and displayed in the <b>Server Console</b>
 tab in the Mac application.

 <p>The Mac application also displays the server's home page
 in a separate tab.

 <!-- ======================================================== -->
 <h2>Running the debug server bound to something other than <tt>localhost</tt></h3>

 <p>Since the web page you want to debug (the debug target) is probably running on
 a different machine (your mobile device) than the debug server (your desktop / laptop),
 you <b>can't</b> use the
 default <tt>localhost</tt> value for the <tt>--boundHost</tt>
 option.  Instead, you will need to specify a host name / ip address
 with the <tt>--boundHost</tt> option.  This host name / ip address
 must be accessible to the machine you want to use as the
 debug target.

 <p>To get started, you can use the value <tt>-all-</tt> for the
 <tt>--boundHost</tt> option.

 <p>Now you'll need to figure out what host name / ip address the
 debug target should use.  If you've use the
 <tt>--boundHost -all-</tt> option, then bring up the debug client
 using the URL <tt>http://localhost:[portNumber]/client/</tt>
 from the same machine the debug server is running on.  On that
 page, under <b>Server Properties</b>, is a list of bound hosts
 that the server believes it's available on.

 <p>From the debug target device (eg, your mobile device),
 try accessing the server home page
 from all of those host names, using the URL
 <tt>http://[host name / ipaddress]:[portNumber]/</tt>.
 Once you find one
 that displays the server's home page correctly, remember
 that host name / ip address, we'll be using it in a minute.

 <div class="note">
 <p>When you run the debug server with a bound host other than
 <tt>localhost</tt>, by definition other machines can now access
 your debug server.  See the <a href="Security.html">Security page</a>
 for information on how to protect yourself.
 </div>

 <!-- ======================================================== -->
 <h2>Instrumenting your web page to act as a debug target</h3>

 <p>At this point you now have a URL to the debug server which
 will be accessible from the debug target.  Let's say that URL
 (to the debug server's home page) is:
 <tt>http://a.b.c:8081</tt>.

 <p>To make your web page debuggable with <span class="weinre">weinre</span>,
 add the following line to your web page:
 <pre>
 &lt;script src="http://a.b.c:8081/target/target-script-min.js"&gt;&lt;/script&gt;
 </pre>

 <p>You can now open a debug client by browsing to
 <tt>http://a.b.c:8081/client</tt>
 (or probably
 <tt>http://localhost:8081/client</tt>
 as well) on your desktop/laptop,
 then reload your newly instrumented web page on your mobile device,
 and see the two connect in the Remote panel of the debug client.

 <!-- ======================================================== -->
 <h2>Hardcoding host names / IP addresses in your web page?</h3>

 <p>Yeah, gross.

 <p>Besides being gross, there are a few practical problems with hardcoding the
 debug server address in your web page as well:

 <ul class="spaced">

 <li>Your html file is probably stored in an SCM, and you
 don't really want to be storing that address in the SCM.
 It won't work for other people using that html file,
 for instance.

 <p>But you don't want to be keeping the
 <tt>&lt;script src=""></tt> line in your SCM either.
 You should look for a way, as part of your personal
 build process to add that line only for development
 builds, and presumably with a user-customizable URL.

 <li>The URL the debug server runs on may be
 different depending on your location.  At work, you may use
 one IP address and host name; at home, you likely have a different
 IP address and host name.  You may not have a host name at all,
 just an IP address (which is fine - a host name isn't required,
 but usually makes things easier).  You may be running on a
 dynamically assigned IP address, in which case your IP
 changes every time you log into your network.

 <p>One way out of the dilemma is to use a dynamic
 DNS solution for the the machine you run the debug server on.
 Doing a web search on the following terms will provide you
 some links to such services:
 <a href="http://www.google.com/search?q=dynamic+dns+static+hostname">dynamic dns static hostname</a>

 <p>If you use one of these dynamic DNS services, you
 can arrange to use the same host name for your debug server
 no matter what network you are connected to.

 </ul>

 <!-- ======================================================== -->
 <h2>Using a bookmarklet</h2>

 <p>Some platforms support 'bookmarkets', which allow you to inject
 arbitrary JavaScript code into any web page running in your
 browser.  Mobile Safari is one of these browsers.  It appears that
 the browser shipped with Android 2.2 and later also supports bookmarklets.

 <p>Unfortunately, installing bookmarkets on mobile devices isn't usually trivial.  The easiest
 course of action is to add a new random bookmark to your bookmarks,
 and then edit it by hand to change the label and URL.  The URL
 you should use is available in both a 'pre' and 'textarea' section
 of the server's home page (eg, http://localhost:8081/).  You should
 be able to select the text from one of these areas easily, to
 paste into the previously added bookmark.

 <p>Once the bookmarklet is installed, you can debug any web page
 by visiting it, and selecting the bookmarklet from your bookmarks
 menu.

 <!-- ======================================================== -->
 <h2>Using the <tt>target/target-script-min.js</tt> file statically</h2>

 <p>If you'd like to use the debug target code statically, instead of
 downloading it from the server all the time, then you will need to do
 one more thing.  The debug target code computes the address of the
 debug server from the <tt>src</tt> attribute in the
 <tt>&lt;script&gt;</tt> tag, and it won't
 be correct in the static case.  Instead you can set the
 following variable to be the URL of the debug server:

 <pre>
 window.WeinreServerURL
 </pre>

 <p>This URL overrides what's otherwise calculated from the debug target
 code itself.  You will need to set this value before the
 <tt>target/target-script-min.js</tt> script is loaded.

 <!-- ======================================================== -->
 <h3>Future Enhancements</h3>

 <p>The calculation of the debug server url by the debug target is a bit fragile and
 ham-fisted.  We should look at additional ways to handle this.
 For instance, we could prompt the user for the debug server
 address, and then always using the debug target in a more static
 mode; eg, you'd include the <tt>target-script-min.js</tt> with all your
 other files in your application.

 <p>Running the debug server on the target device is another option.
 This shouldn't be a huge problem for Android, but is more of a problem
 on iOS.  By running the debug server on the target device, the
 debug target can always connect to the debug server by using a
 <tt>localhost</tt> hostname.  The debug client, running on your
 desktop/laptop, would then need to connect to the target device
 to debug.  In practice this may be an easier scenario to work with,
 as the potentially changing IP address of the mobile device just
 means having to type a different URL in your web browser on your desktop / laptop
 when running the debug client. That's easier than hard-coding
 URLs in your web page, for instance.


 <!--
  * weinre is available under *either* the terms of the modified BSD license *or* the
  * MIT License (2008). See http://opensource.org/licenses/alphabetical for full text.
  *
  * Copyright (c) 2010, 2011 IBM Corporation
 -->

 <div class="toc">
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 <p>
   <a href="Home.html">Home</a>
 - <a href="TestDrive.html">Test Drive</a>
 - <a href="Installing.html">Installing</a>
 - <a href="Running.html">Running</a>
 - <a href="MultiUser.html">Multi-User</a>
 - <a href="Security.html">Security</a>
 - <a href="Building.html">Building</a>
 - <a href="ChangeLog.html">ChangeLog</a>
 - <a href="License.html">License</a>

 <br><img src="images/weinre-icon-128x128.png">
 </div>

 </body>
 </html>
	<!doctype html>

	<!--
	* weinre is available under either the terms of the modified BSD license or the
	* MIT License (2008). See http://opensource.org/licenses/alphabetical for full text.
	*
	* Copyright (c) 2010, 2011 IBM Corporation
	-->

	<html>
	<head>
	<title>weinre - Running</title>
	<link rel="stylesheet" href="css/main.css" type="text/css">
	<link rel="shortcut icon" href="images/weinre-icon-64x64.png" />
	<script src="scripts/main.js"></script>
	<script type="text/javascript">

	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-736164-7']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();

	</script>
	</head>

	<body>

	<a class="no-decoration" href="https://github.com/phonegap/weinre"><div class="ribbon">Fork weinre on GitHub</div></a>

	<!-- ======================================================================= -->
	<h1 class="page-title">weinre - Running</h1>

	<div class="toc">
	<a href="Home.html">Home</a>
	- <a href="TestDrive.html">Test Drive</a>
	- <a href="Installing.html">Installing</a>
	- <a href="Running.html">Running</a>
	- <a href="MultiUser.html">Multi-User</a>
	- <a href="Security.html">Security</a>
	- <a href="Building.html">Building</a>
	- <a href="ChangeLog.html">ChangeLog</a>
	- <a href="License.html">License</a>
	<p>
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	</div>

	<!--
	* weinre is available under either the terms of the modified BSD license or the
	* MIT License (2008). See http://opensource.org/licenses/alphabetical for full text.
	*
	* Copyright (c) 2010, 2011 IBM Corporation
	-->

	<p>This page describes how to use <span class="weinre">weinre</span> to debug
	your own web pages on a remote device.

	<p>First, some background.

	<!-- ======================================================== -->
	<h2>Terminology</h2>

	<p>When using <span class="weinre">weinre</span>, there are three programs interacting with
	each other.

	<dl class="spaced">

	<dt>Debug Server
	<dd>This is the HTTP server that you run from the <tt>weinre.jar</tt> file
	or the Mac application. It's the HTTP server that's used by the
	<b>Debug Client</b> and <b>Debug Target</b>.

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

	<dt>Debug Target
	<dd>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 <span class="weinre">weinre</span> is to allow
	debugging applications on mobile devices, the debug
	target, when speaking of the machine, is your mobile
	device.

	</dl>

	<p>Both the <b>Debug Client</b> and the <b>Debug Target</b> communicate to
	the <b>Debug Server</b> via HTTP using <tt>XMLHttpRequest</tt> (XHR).

	<p>Typically, you run both the <b>Debug Client</b> and the <b>Debug Server</b>
	on your desktop/laptop, and the <b>Debug Target</b> on your mobile device.

	<p>When using the Mac application, the
	<b>Debug Client</b> and <b>Debug Server</b> are running
	in the same process.
	When you launch the application,
	the server starts, and then the browser included in the
	application is launched
	on the appropriate URL automagically.

	<p>When using the <tt>weinre.jar</tt> program instead
	of the Mac application, only the <b>Debug Server</b>
	is started. You will need to launch the <b>Debug Client</b>
	in a web browser.

	<p>The <b>Debug Target</b> is the squirrelliest bit. You
	will need to arrange to inject some JavaScript code, provided
	by the <b>Debug Server</b>, into your web page, in order for it
	to function as a <b>Debug Target</b>.

	<!-- ======================================================== -->
	<h2>Starting the debug server</h2>

	<p>There are two ways to run the <span class="weinre">weinre</span> debug server:

	<ul>
	<li>Running the debug server using the weinre.jar file
	<li>Running the debug server using the Mac application
	</ul>

	<!-- ======================================================== -->
	<h2>Running the debug server using the weinre.jar file</h2>

	<p>To run <span class="weinre">weinre</span> from the jar file,
	execute the following command:

	<pre>
	java -jar path/to/weinre.jar [options]
	</pre>

	<p>Options available are:

	<ul class="spaced no-bullet">

	<li><tt>--help</tt> (or <tt>-?</tt> or <tt>-h</tt>)
	<div class="indent">
	<p>Display this help.
	</div>

	<li><tt>--httpPort [portNumber]</tt>
	<div class="indent">
	<p>The port to run the HTTP server on.
	<p>Default: <tt>8080</tt>
	</div>

	<li><tt>--boundHost [hostname \| ip address \| -all-]</tt>
	<div class="indent">
	<p>The ip address to bind the server to.
	<p>Default: <tt>localhost</tt>

	<p>With the default of <tt>localhost</tt>, you won't be able to access
	the server from any machine other than the one the server is running on. You will
	need to bind to another hostname / ip address to make the server accessible to other
	machines. You can use the value <tt>-all-</tt> to indicate that you
	want to bind to all interfaces available on the current machine.

	<p>Use <tt>ifconfig</tt> on Linux or the Mac, and <tt>ipconfig</tt>
	on Windows, to get the ip addresses available on your machine.
	</div>

	<li><tt>--verbose [true \| false]</tt>
	<div class="indent">
	<p>Causes jibberish to be written to stdout
	<p>Default: <tt>false</tt>
	</div>

	<li><tt>--reuseAddr [true \| false]</tt>
	<div class="indent">
	<p>Sets the "reuseAddr" flag for Jetty.
	<p>Default: <tt>false</tt>

	<p>May be needed if you restart your server frequently.
	</div>

	<li><tt>--readTimeout [seconds]</tt>
	<div class="indent">
	<p>The number of seconds the server will wait for a message
	to be available to send to the target or client.
	<p>Default: <tt>5</tt>

	<p>Can probably be set larger, but then your browser may
	time out. Probably don't want to set it much lower than
	this as it will cause additional network traffic when
	no messages are being sent (it will cause more "empty"
	messages to be sent).
	</div>

	<li><tt>--deathTimeout [seconds]</tt>
	<div class="indent">
	<p>The number of seconds to wait to hear back from a
	debug client or target before declaring them dead.
	<p>Default: <tt>3 * readTimeout</tt>

	<p>Normally the default will be fine. However, if
	you're debugging <span class="weinre">weinre</span> itself, you may wish to set
	it much longer.
	</div>

	</ul>

	<p>You may also create a file named
	<tt>server.properties</tt> in the
	directory <tt>.weinre</tt> in your
	home directory (eg.
	<tt>~/.weinre/server.properties</tt>).
	The keys should be
	the same as the name of the options above,
	with the same values.

	<p>As an example, your <tt>~/.weinre/server.properties</tt>
	file might look like this:

	<pre>
	boundHost: -all-
	httpPort: 8081
	reuseAddr: true
	readTimeout: 1
	deathTimeout: 5
	</pre>

	<p>Command-line options override the options specified in the
	<tt>~/.weinre/server.properties</tt> file.

	<p>The server will run until you kill it. Control-C will do the job.

	<!-- ======================================================== -->
	<h2>Running the debug server using the Mac application</h2>

	<p>Go back and read the description above about the weinre.jar settings.

	<p>Only the <tt>~/.weinre/server.properties</tt>
	file is available to configure the server, as there is no
	traditional command line used to launch Mac "applications".

	<p>The server will run until you quit the application.

	<p>Since there is no practical way to see the stdout and stdin
	from the server when running a Mac application, these streams
	are intercepted and displayed in the <b>Server Console</b>
	tab in the Mac application.

	<p>The Mac application also displays the server's home page
	in a separate tab.

	<!-- ======================================================== -->
	<h2>Running the debug server bound to something other than <tt>localhost</tt></h3>

	<p>Since the web page you want to debug (the debug target) is probably running on
	a different machine (your mobile device) than the debug server (your desktop / laptop),
	you <b>can't</b> use the
	default <tt>localhost</tt> value for the <tt>--boundHost</tt>
	option. Instead, you will need to specify a host name / ip address
	with the <tt>--boundHost</tt> option. This host name / ip address
	must be accessible to the machine you want to use as the
	debug target.

	<p>To get started, you can use the value <tt>-all-</tt> for the
	<tt>--boundHost</tt> option.

	<p>Now you'll need to figure out what host name / ip address the
	debug target should use. If you've use the
	<tt>--boundHost -all-</tt> option, then bring up the debug client
	using the URL <tt>http://localhost:[portNumber]/client/</tt>
	from the same machine the debug server is running on. On that
	page, under <b>Server Properties</b>, is a list of bound hosts
	that the server believes it's available on.

	<p>From the debug target device (eg, your mobile device),
	try accessing the server home page
	from all of those host names, using the URL
	<tt>http://[host name / ipaddress]:[portNumber]/</tt>.
	Once you find one
	that displays the server's home page correctly, remember
	that host name / ip address, we'll be using it in a minute.

	<div class="note">
	<p>When you run the debug server with a bound host other than
	<tt>localhost</tt>, by definition other machines can now access
	your debug server. See the <a href="Security.html">Security page</a>
	for information on how to protect yourself.
	</div>

	<!-- ======================================================== -->
	<h2>Instrumenting your web page to act as a debug target</h3>

	<p>At this point you now have a URL to the debug server which
	will be accessible from the debug target. Let's say that URL
	(to the debug server's home page) is:
	<tt>http://a.b.c:8081</tt>.

	<p>To make your web page debuggable with <span class="weinre">weinre</span>,
	add the following line to your web page:
	<pre>
	<script src="http://a.b.c:8081/target/target-script-min.js"></script>
	</pre>

	<p>You can now open a debug client by browsing to
	<tt>http://a.b.c:8081/client</tt>
	(or probably
	<tt>http://localhost:8081/client</tt>
	as well) on your desktop/laptop,
	then reload your newly instrumented web page on your mobile device,
	and see the two connect in the Remote panel of the debug client.

	<!-- ======================================================== -->
	<h2>Hardcoding host names / IP addresses in your web page?</h3>

	<p>Yeah, gross.

	<p>Besides being gross, there are a few practical problems with hardcoding the
	debug server address in your web page as well:

	<ul class="spaced">

	<li>Your html file is probably stored in an SCM, and you
	don't really want to be storing that address in the SCM.
	It won't work for other people using that html file,
	for instance.

	<p>But you don't want to be keeping the
	<tt><script src=""></tt> line in your SCM either.
	You should look for a way, as part of your personal
	build process to add that line only for development
	builds, and presumably with a user-customizable URL.

	<li>The URL the debug server runs on may be
	different depending on your location. At work, you may use
	one IP address and host name; at home, you likely have a different
	IP address and host name. You may not have a host name at all,
	just an IP address (which is fine - a host name isn't required,
	but usually makes things easier). You may be running on a
	dynamically assigned IP address, in which case your IP
	changes every time you log into your network.

	<p>One way out of the dilemma is to use a dynamic
	DNS solution for the the machine you run the debug server on.
	Doing a web search on the following terms will provide you
	some links to such services:
	<a href="http://www.google.com/search?q=dynamic+dns+static+hostname">dynamic dns static hostname</a>

	<p>If you use one of these dynamic DNS services, you
	can arrange to use the same host name for your debug server
	no matter what network you are connected to.

	</ul>

	<!-- ======================================================== -->
	<h2>Using a bookmarklet</h2>

	<p>Some platforms support 'bookmarkets', which allow you to inject
	arbitrary JavaScript code into any web page running in your
	browser. Mobile Safari is one of these browsers. It appears that
	the browser shipped with Android 2.2 and later also supports bookmarklets.

	<p>Unfortunately, installing bookmarkets on mobile devices isn't usually trivial. The easiest
	course of action is to add a new random bookmark to your bookmarks,
	and then edit it by hand to change the label and URL. The URL
	you should use is available in both a 'pre' and 'textarea' section
	of the server's home page (eg, http://localhost:8081/). You should
	be able to select the text from one of these areas easily, to
	paste into the previously added bookmark.

	<p>Once the bookmarklet is installed, you can debug any web page
	by visiting it, and selecting the bookmarklet from your bookmarks
	menu.

	<!-- ======================================================== -->
	<h2>Using the <tt>target/target-script-min.js</tt> file statically</h2>

	<p>If you'd like to use the debug target code statically, instead of
	downloading it from the server all the time, then you will need to do
	one more thing. The debug target code computes the address of the
	debug server from the <tt>src</tt> attribute in the
	<tt><script></tt> tag, and it won't
	be correct in the static case. Instead you can set the
	following variable to be the URL of the debug server:

	<pre>
	window.WeinreServerURL
	</pre>

	<p>This URL overrides what's otherwise calculated from the debug target
	code itself. You will need to set this value before the
	<tt>target/target-script-min.js</tt> script is loaded.

	<!-- ======================================================== -->
	<h3>Future Enhancements</h3>

	<p>The calculation of the debug server url by the debug target is a bit fragile and
	ham-fisted. We should look at additional ways to handle this.
	For instance, we could prompt the user for the debug server
	address, and then always using the debug target in a more static
	mode; eg, you'd include the <tt>target-script-min.js</tt> with all your
	other files in your application.

	<p>Running the debug server on the target device is another option.
	This shouldn't be a huge problem for Android, but is more of a problem
	on iOS. By running the debug server on the target device, the
	debug target can always connect to the debug server by using a
	<tt>localhost</tt> hostname. The debug client, running on your
	desktop/laptop, would then need to connect to the target device
	to debug. In practice this may be an easier scenario to work with,
	as the potentially changing IP address of the mobile device just
	means having to type a different URL in your web browser on your desktop / laptop
	when running the debug client. That's easier than hard-coding
	URLs in your web page, for instance.



	<!--
	* weinre is available under either the terms of the modified BSD license or the
	* MIT License (2008). See http://opensource.org/licenses/alphabetical for full text.
	*
	* Copyright (c) 2010, 2011 IBM Corporation
	-->

	<div class="toc">
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	<p>
	<a href="Home.html">Home</a>
	- <a href="TestDrive.html">Test Drive</a>
	- <a href="Installing.html">Installing</a>
	- <a href="Running.html">Running</a>
	- <a href="MultiUser.html">Multi-User</a>
	- <a href="Security.html">Security</a>
	- <a href="Building.html">Building</a>
	- <a href="ChangeLog.html">ChangeLog</a>
	- <a href="License.html">License</a>

	<br><img src="images/weinre-icon-128x128.png">
	</div>

	</body>
	</html>