<!--
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
-->

<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-node</tt> distribution.
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>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>Running the debug server using an <tt>npm</tt> installation</h2>

<p>To run <span class="weinre">weinre</span> from an <tt>npm</tt>
installation, assuming you've installed it globally (in the <tt>npm</tt>
sense), execute the following command:

<pre>
weinre [options]
</pre>

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

<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>--debug [true | false]</tt>
<div class="indent">
<p>Causes even more jibberish to be written to stdout
<p>Default: <tt>false</tt>
</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>

<!-- ======================================================== -->
<h2>The <tt>~/.weinre/server.properties</tt> file</h2>

<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>).
Your home directory is the determined by the value of either the
<tt>HOME</tt> or <tt>USERPROFILE</tt> environment variable.

<p>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.

<!-- ======================================================== -->
<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.