Add a build step / documentation for code reuse

Trac: 32499

.gitignore

@@ -13,6 +13,7 @@ snowflake.log
 proxy/test
 proxy/build
 proxy/node_modules
+proxy/snowflake-library.js
 proxy/spec/support
 proxy/webext/snowflake.js
 proxy/webext/popup.js

proxy/.eslintignore

@@ -1,6 +1,7 @@
 build/
 test/
 webext/snowflake.js
+snowflake-library.js
 
 # FIXME: Whittle these away
 spec/

proxy/README.md

@@ -7,12 +7,26 @@ See https://snowflake.torproject.org/ for more info:
 <iframe src="https://snowflake.torproject.org/embed.html" width="88" height="16" frameborder="0" scrolling="no"></iframe>
 ```
 
-### Building
+### Building the badge / snowflake.torproject.org
 
 ```
+npm install
 npm run build
 ```
 
+which outputs to the `build/` directory.
+
+### Building the webextension
+
+```
+npm install
+npm run webext
+```
+
+and then load the `webext/` directory as an unpacked extension.
+ * https://developer.mozilla.org/en-US/docs/Tools/about:debugging#Loading_a_temporary_extension
+ * https://developer.chrome.com/extensions/getstarted#manifest
+
 ### Testing
 
 Unit testing with Jasmine are available with:
@@ -44,6 +58,7 @@ IdentityFile ~/.ssh/tor
 ### Deploying
 
 ```
+npm install
 npm run build
 ```
 
@@ -73,3 +88,50 @@ With no parameters,
 snowflake uses the default relay `snowflake.freehaven.net:443` and
 uses automatic signaling with the default broker at
 `https://snowflake-broker.freehaven.net/`.
+
+### Reuse as a library
+
+The badge and the webextension make use of the same underlying library and
+only differ in their UI.  That same library can be produced for use with other
+interfaces, such as [Cupcake][1], by running,
+
+```
+npm install
+npm run library
+```
+
+which outputs a `./snowflake-library.js`.
+
+You'd then want to create a subclass of `UI` to perform various actions as
+the state of the snowflake changes,
+
+```
+class MyUI extends UI {
+    ...
+}
+```
+
+See `WebExtUI` in `init-webext.js` and `BadgeUI` in `init-badge.js` for
+examples.
+
+Finally, initialize the snowflake with,
+
+```
+var log = function(msg) {
+  return console.log('Snowflake: ' + msg);
+};
+var dbg = log;
+
+var config = new Config();
+var ui = new MyUI();  // NOTE: Using the class defined above
+var broker = new Broker(config.brokerUrl);
+
+var snowflake = new Snowflake(config, ui, broker);
+
+snowflake.setRelayAddr(config.relayAddr);
+snowflake.beginWebRTC();
+```
+
+This minimal setup is pretty much what's currently in `init-node.js`.
+
+[1]: https://chrome.google.com/webstore/detail/cupcake/dajjbehmbnbppjkcnpdkaniapgdppdnc

proxy/make.js

@@ -39,7 +39,10 @@ var SHARED_FILES = [
 ];
 
 var concatJS = function(outDir, init, outFile, pre) {
-  var files = FILES.concat(`init-${init}.js`);
+  var files = FILES;
+  if (init) {
+    files = files.concat(`init-${init}.js`);
+  }
   var outPath = `${outDir}/${outFile}`;
   writeFileSync(outPath, pre, 'utf8');
   execSync(`cat ${files.join(' ')} >> ${outPath}`);
@@ -176,6 +179,11 @@ task('clean', 'remove all built files', function() {
   execSync('rm -rf build test spec/support');
 });
 
+task('library', 'build the library', function() {
+  concatJS('.', '', 'snowflake-library.js', '');
+  console.log('Library prepared.');
+});
+
 var cmd = process.argv[2];
 
 if (tasks.has(cmd)) {

proxy/package.json

@@ -10,6 +10,7 @@
     "test": "node make.js test",
     "build": "node make.js build",
     "webext": "node make.js webext",
+    "library": "node make.js library",
     "pack-webext": "node make.js pack-webext",
     "clean": "node make.js clean",
     "prepublish": "node make.js node",

proxy/webext/README.md

@@ -1,11 +0,0 @@
-Build it,
-
-```
-cd ..
-npm install
-npm run webext
-```
-
-and then load this directory as an unpacked extension.
- * https://developer.mozilla.org/en-US/docs/Tools/about:debugging#Loading_a_temporary_extension
- * https://developer.chrome.com/extensions/getstarted#manifest