385 lines
14 KiB
HTML
385 lines
14 KiB
HTML
<!doctype html>
|
|
|
|
<!--
|
|
* 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.
|
|
-->
|
|
|
|
<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" />
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="ribbon">clone weinre at
|
|
<a href="https://git-wip-us.apache.org/repos/asf?p=cordova-weinre.git">apache</a>
|
|
</div>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h1 class="page-title">weinre - Running</h1>
|
|
|
|
<div class="toc">
|
|
<a href="Home.html">Home</a>
|
|
- <a href="UserInterface.html">User Interface</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>
|
|
|
|
<!--
|
|
* 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>
|
|
<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.
|
|
|
|
|
|
<!--
|
|
* 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.
|
|
-->
|
|
|
|
<div class="toc">
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
<p>
|
|
<a href="Home.html">Home</a>
|
|
- <a href="UserInterface.html">User Interface</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>
|