Add github pull request template
[cordova-weinre.git] / README.md
1 <!--
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  You may obtain a copy of the License at
9  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing,
13  * software distributed under the License is distributed on an
14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15  * KIND, either express or implied.  See the License for the
16  * specific language governing permissions and limitations
17  * under the License.
18 -->
19
20 weinre is WEb INspector REmote.
21
22 Pronounced like the word "winery". Or maybe like the word "weiner".
23 Who knows, really.
24
25 weinre is a debugger for web pages,
26 like FireBug (for FireFox) and Web Inspector (for WebKit-based browsers),
27 except it's designed to work remotely, and in particular,
28 to allow you debug web pages on a mobile device such as a phone.
29
30 weinre is part of the
31 [Apache Cordova project](http://cordova.io/).
32
33 For descriptive information, and links to downloads, installable things, etc
34 see: [http://people.apache.org/~pmuellr/weinre/](http://people.apache.org/~pmuellr/weinre/)
35
36 weinre source
37 -------------
38
39 The weinre source is contained in 4 subdirectories:
40
41 * `weinre.build` - contains the tools to build weinre, the 3rd party libraries
42 that weinre uses, and holds the output of the build
43
44 * `weinre.doc` - source for the HTML manual for weinre
45
46 * `weinre.server` - code for the node.js-based weinre server
47
48 * `weinre.web` - code for the client and target pieces of weinre
49
50
51 building weinre
52 ---------------
53
54 The weinre build is currently run on a Mac OS X 10.7 laptop.  It also runs on
55 Apache continuous integration servers running Linux.  The build is not
56 typically run on Windows, so if you have problems with that, please log an
57 issue.
58
59 The weinre build pre-req's the following tools:
60
61 * node.js - [http://nodejs.org/](http://nodejs.org/)
62 * ant - [http://ant.apache.org/](http://ant.apache.org/)
63
64 To update the npm-based pre-reqs, you will also need:
65
66 * npm - should be shipped with node.js, on Linux may need to be installed as a
67 separate package
68
69 Before doing a weinre build, you will need to create the file
70 `weinre.build/personal.properties`.  Use the `sample.personal.properties` as a
71 template. The build should fail if this file is not available.
72
73 To update the version label of weinre, edit the file
74 `weinre.build/build.properties`.  If the version has a `-pre` suffix, this
75 triggers the build to artifacts with timestamped names.  For an 'official'
76 build, do not use the `-pre` suffix.
77
78 There are two ways to build weinre:
79
80 * full build
81 * development build
82
83 The full build creates all the artifacts needed for an 'official' build.
84
85 The development build just creates enough artifacts to test the code.
86
87 ### the first time you run any build: ###
88
89 Some semi-transient artifacts are created the first time you run a build.
90 These will be stored in the `weinre.build/cached` directory.
91
92 ### to perform the full build: ###
93
94 * run: `cd weinre.build`
95 * run: `ant build-archives`
96
97 This will run the development build (see below), and then create zip archives
98 of the build in the `weinre.build/out/archives` directory.
99
100 ### to perform the development build: ###
101
102 * run: `cd weinre.build`
103 * run: `ant`
104
105 This will populate a number of resources in the `weinre.server` directory, so
106 that you can run weinre directly from that directory for testing.  It does not
107 build the archives.
108
109 ### performing a clean build: ###
110
111 * run: `cd weinre.build`
112 * run: `ant clean`
113 * perform the build as usual
114
115 ### other ant goodies: ###
116
117 * run: `cd weinre.build`
118 * run: `ant help`
119
120 ### to run the output of the development build: ###
121
122 * run: `cd weinre.server`
123 * run: `./weinre [your flavorite options]`
124
125 ### other fun development-time hacks ###
126
127 If you have the [wr tool](https://npmjs.org/package/wr) installed, there is
128 a `.wr` file available to run the development builds when a source file
129 changes.
130
131 The build is growl-enabled, so you can see a quick message when the build
132 completes, as long as the `USE_GROWL` property is set in the
133 `weinre.build/personal.properties` file.
134
135 The command `weinre.server/weinre-hot` makes use of
136 [node-supervisor](https://github.com/isaacs/node-supervisor) to re-launch the
137 weinre server generated by the development build, whenever a weinre build
138 completes.
139
140 Putting this altogether, you can open two terminal windows, run `wr` in the
141 main directory to have a development build run whenever you change
142 the source, and then run `weinre-hot` in the `weinre.server` directory to have
143 the weinre server restart whenever a build completes, getting a growl
144 notification at that time.
145
146 updating 3rd party libraries
147 -----------------------------
148
149 > **IMPORTANT** - All 3rd party libraries are stored in the SCM, so that the
150 build does not require 3rd party packages to be downloaded.  As such, these
151 files need to be ok to use and store in the SCM, given their licenses.  If
152 you're adding or updating a 3rd party library, make sure the license is
153 acceptable, and add/update the license in the top-level `LICENSE` file.
154
155 All of the 3rd party dependencies used with weinre are stored in one of two
156 directories:
157
158 * `weinre.build/vendor` - contains libraries used in the client and/or target,
159 as well as libraries used by the build itself
160
161 * `weinre.server/node_modules` - contains npm packages used by the weinre server
162
163 To update the files in `weinre.build/vendor`:
164
165 * edit the file `weinre.build/vendor.properties` as appropriate
166 * run: `cd weinre.build`
167 * run: `rm -rf vendor`
168 * run: `ant -f update.vendor.xml`
169
170 To update the files in `weinre.server/node_modules`:
171
172 * edit the file `weinre.build/package.json.template` as appropriate
173 * run a build (see above), so that the file `weinre.server/package.json` file is created
174 from the template you edited above
175 * run: `cd weinre.server`
176 * run: `rm -rf node_modules`
177 * run: `npm install`