You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+15-38Lines changed: 15 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,7 +15,7 @@ uProxy is built using the following tools:
15
15
-[TypeScript](http://www.typescriptlang.org/) as the primary language we code in; this compiles to JavaScript. It gives us type-checking and has some syntax improvements on JS, while letting us incrementally migrate and easily include external JS packages and frameworks.
16
16
-[Jasmine](http://pivotal.github.io/jasmine/) for testing
17
17
-[Polymer](http://www.polymer-project.org/) for UI
18
-
18
+
19
19
To manage dependencies we use:
20
20
-[npm](https://www.npmjs.org/) for installing node modules that we use for our build process. (Specified in `package.json`)
21
21
-[Bower](http://bower.io) to install libraries that we use in the UI
@@ -58,16 +58,13 @@ modify (`/usr/local`) to being editable by your user (sudo chown -R $USER /usr/l
58
58
1. Clone uProxy and its submodules (and its submodules' submodules...): `git clone https://github.com/uProxy/uProxy.git` or `git clone git@github.com:uProxy/uproxy.git` if you have your ssh access to github set up (useful if you use 2-step auth for github, which you should do).
59
59
60
60
1. In the root uProxy directory, run:
61
-
*`npm install` - this will install all node npm module development dependencies; you'll see lots of npm messages. (watch out for errors; sometimes npm module installation is broken, downloads fail etc). This will also install the static content dependencies (mostly Polymer components).
62
61
*`./setup.sh install` - this will set up build tools and third-party dependencies.
63
62
*`grunt` - this will build everything, including uProxy for Chrome and Firefox.
64
63
65
-
Note that if any local dependencies have changed (i.e. changes to bower dependencies, updates to FreeDOM), you will have to run `npm update` and/or `bower install` to update these dependencies, then rerun `grunt`
64
+
Note that if any local dependencies have changed (i.e. changes to bower dependencies, updates to FreeDOM), you will have to run `./setup.sh install` to update these dependencies, then rerun `grunt`
66
65
67
66
### Installing and running
68
67
69
-
*Please don’t submit uProxy to the Chrome Web Store or Firefox Marketplace*. uProxy is under active development and the team takes its responsibility to provide security very seriously; we don’t want at-risk groups that may not be technically sophisticated — journalists, human-rights workers, et al — to rely on uProxy until we feel it’s ready. Prematurely making uProxy available could have very serious real world ramifications. Before we release uProxy to the browser stores, we want the source code examined and reviewed so that the community as a whole can help us make sure that we haven’t overlooked anything in our implementation. Once we feel that uProxy is ready, we will release it via the browser web stores ourselves.
70
-
71
68
#### Chrome
72
69
73
70
These are the steps to try uProxy in the Chrome browser.
@@ -94,54 +91,33 @@ Instructions can be found here: https://developer.mozilla.org/en-US/Add-ons/SDK/
94
91
95
92
You can use `grunt build_firefox` from the root directory of the repository to compile just Firefox comonents.
96
93
97
-
98
-
#### Starting two instances of Chrome on the same machine
99
-
100
-
To test proxying without using multiple computers, you can launch two separate instances of Chrome (specifying different directories for user-data-dir). To launch a new instance of Chrome on Mac, run:
where DIR_NAME is set to the name of a directory where you want to store custom chrome profiles, e.g. `/tmp/`.
103
-
104
-
In each instance of Chrome, load the uProxy app and extension as describe above.
105
-
106
-
You can also test between one instance of Chrome and one instance in Firefox.
107
-
108
-
Then in each instance, within uProxy, sign into Google with gmail accounts that have already added each other as contacts. After sign-in both contacts should be visible on each other's roster. Once proxying is started in the UI, try visiting any web page from the client's Chrome window. To verify that traffic is actually being proxied, open the debug console for the server's uProxy Chrome App. You should see traces indicating the flow of traffic through the proxy.
109
-
110
94
### Development and re-building uProxy
111
95
112
96
uProxy uses the Grunt build system for its build tasks. Here is a list
113
97
of uProxy's Grunt commands:
114
98
115
99
*`build` - Builds everything, making stuff in the `build` directory (and runs tests).
116
100
*`build_chrome` - Build Chrome app and extension
117
-
*`build_chrome_app` - Build just Chrome app
118
-
*`build_chrome_extension` - Build just Chrome extension
101
+
*`build_chrome_app` - Build just Chrome app
102
+
*`build_chrome_ext` - Build just Chrome extension
119
103
*`build_firefox` - Build just Firefox
120
-
*`build_uistatic` - Build the static UI.
104
+
*`dist` - Generates distribution files, including the Firefox xpi
121
105
*`clean` - Cleans up
122
-
*`watch` - Watch for changes and recompile as needed.
123
106
*`test` - Run unit tests
124
-
*`xpi` - Generates an .xpi for installation to Firefox.
125
-
*`run_uistatic` - Run the standalone UI on a local webserver.
126
107
*`everything` - 'test', then 'build'
127
108
128
109
The easiest way to stay current is to pull changes, run `grunt build` to build
129
-
your distribution, then run `grunt watch`, which will rebuild as you make changes. (TODO: grunt watch is broken; fix it!)
110
+
your distribution, and re-run as you make changes to the files.
130
111
131
112
Before submitting any changes to the repository, make sure to run `grunt test`
132
-
to make sure it passes all unit tests. Failing tests are cause to immediately
113
+
to make sure it passes all unit tests. Failing tests are enough to immediately
133
114
reject submissions. :)
134
115
135
116
136
117
### Fixing compilation and setup
137
118
138
-
The following hints may help you if it goes wrong and you need to debug and fix it.
139
-
140
-
- The file called `package.json` provides details of node packages used to build uProxy. To download and install them in the right place (typically a subdirectory called `node_packages`) run `npm install`.
141
-
142
-
- A file called `bower.json` provides details of packages for the UI, typically JavaScript for the browser. Run `bower install` to download and install the dependencies. They are typically installed in a directory called `lib` (as defined by a local file called `.bowerrc`).
143
-
144
-
- If bower fails, it doesn't tell you. Sometimes things don't work because it failed to install something that you need. When you run `bower install`, look out for error messages.
119
+
- If something is going wrong during the build process, please try running `grunt
120
+
clean`, `./setup.sh clean`, and re-running `./setup.sh install`
145
121
146
122
- If things are not working, check that you have recent versions of bower, npm, and node.
147
123
@@ -155,24 +131,25 @@ Configuration and setup files
155
131
*`.gitignore` what git should ignore
156
132
*`.bowerrc` tells bower where to put files
157
133
*`.travis.yml` Travis auto-testing
158
-
*`tools` directory contains some typescript and javascript to help Grunt.
134
+
*`tools` directory contains some typescript and javascript to help Grunt.
135
+
*`third_party/tsd.json` specifies the typescript definitions to use
0 commit comments