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