Commit 127f1e06b127fbdfba1b9259fa62bd0a6bdb3050
readme fix
andre alves garzia committed on 6/28/2018, 11:20:29 PMParent: 851531c0e3ba49e7d6301e1941f7cf92e8f91628
Files changed
| README.md | changed |
| README.md | |||
|---|---|---|---|
| @@ -1,65 +1,44 @@ | |||
| 1 … | + | ||
| 1 | 2 … | ||
| 2 | -## Native companion app | ||
| 3 | -This repository also contains a native companion app that is able to supply features for Firefox WebExtensions posting to the [scuttlebutt](https://www.scuttlebutt.nz/) platform. | ||
| 3 … | +# Scuttle Shell | ||
| 4 | 4 … | ||
| 5 | -This is useful because there are no WebExtension APIs for TCP and UDP so we can't implement the correct protocols for scuttlebutt. Instead we have a way to use the [Native Messaging API](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging) to establish communication between a native application (this app) and an authorized WebExtension. We can think of it much like we do with back-end and front-end web programming, this app is the back-end providing features and all the authorized add-ons are front-end interfacing with Firefox users. | ||
| 5 … | +This is a [Secure Scuttlebutt](http://scuttlebutt.nz) system tray application. It provides an always-running _sbot_ for your local system. | ||
| 6 | 6 … | ||
| 7 | -**Be aware that the companion app is not a requirement, Patchfox can use WebSockets to communicate with a running _sbot_.** So you can run Patchfox in parallel with other clients that start their own _sbot_ or even start it from the command-line with `sbot serve`. Still, this companion app makes it effortless to use Patchfox. | ||
| 7 … | +## Install globally | ||
| 8 | 8 … | ||
| 9 | -### Dependencies | ||
| 9 … | +``` | ||
| 10 … | +$ npm install -g | ||
| 11 … | +``` | ||
| 10 | 12 … | ||
| 11 | -This native application is [NodeJS](https://nodejs.org) based and you need to have a recent version of it installed. | ||
| 13 … | +You can run the app by executing `scuttleshell` on your terminal. | ||
| 12 | 14 … | ||
| 13 | -#### How to setup the native app | ||
| 15 … | +## Setup | ||
| 14 | 16 … | ||
| 15 | -You need to install the dependencies first: | ||
| 17 … | +This application is built with [NodeJS](https://nodejs.org). To set it up run: | ||
| 16 | 18 … | ||
| 17 | 19 … | ``` | |
| 18 | 20 … | $ npm install | |
| 19 | 21 … | ``` | |
| 20 | 22 … | ||
| 21 | -After that the procedure changes depending on which OS you're running as the configuration of _native apps_ differs by operating system with Windows being a quite convoluted process. To setup the application, meaning place the correct _app manifest_ json in the correct place and fix the paths, run: | ||
| 23 … | +This should set it up. If anything fails you can check your setup with | ||
| 22 | 24 … | ||
| 23 | -``` | ||
| 24 | -$ npm run setup-win | ||
| 25 | -``` | ||
| 26 | 25 … | ||
| 27 | -or | ||
| 26 … | +### Checking your setup | ||
| 27 … | +Depending on your running operating system, you can check the configuration using: | ||
| 28 | 28 … | ||
| 29 | 29 … | ``` | |
| 30 | -$ npm run setup | ||
| 30 … | +$ npm run check | ||
| 31 | 31 … | ``` | |
| 32 | 32 … | ||
| 33 | -Depending if you're running Windows 10 or other operating system. Also, if you are running under a unix-like system, you will need to double check the shebang invocation on top of the `index.js` file to make sure that it points to your NodeJS location. I tried using `env` there but it didn't work when started from inside Firefox, so it is hardcoded to the default location of NodeJS installation. | ||
| 33 … | +or | ||
| 34 | 34 … | ||
| 35 | -Be aware that the setup procedure will place hardcoded paths in files critical for running this app. **If you move this application to a different folder or rename any folder in its path, you'll need to run this setup again.** | ||
| 36 | - | ||
| 37 | -#### Verifying your configuration | ||
| 38 | - | ||
| 39 | -Run the verification script as: | ||
| 40 | - | ||
| 41 | 35 … | ``` | |
| 42 | 36 … | $ npm run check-win | |
| 43 | 37 … | ``` | |
| 44 | 38 … | ||
| 45 | -or | ||
| 39 … | +### Running Setup (again) | ||
| 40 … | +If anything went wrong during the setup or if you rename the folder this app is in, you can redo the setup with: | ||
| 46 | 41 … | ||
| 47 | 42 … | ``` | |
| 48 | -$ npm run check | ||
| 49 | -``` | ||
| 50 | - | ||
| 51 | -Depending if you're running Windows 10 or other operating system. | ||
| 52 | - | ||
| 53 | -# How to install the add-on | ||
| 54 | - | ||
| 55 | -On [Firefox Nightly (or Firefox Dev Edition)](https://www.mozilla.org/firefox/channel/desktop/) go to _about:debugging_ and use the _load temporary add-on_ button to browse your files. Select the _manifest.json_ file included with this repository in the `webextension/build` folder. | ||
| 56 | - | ||
| 57 | -To learn more about WebExtension development and debugging, go to [MDN Web Docs - WebExtensions](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/). | ||
| 58 | - | ||
| 59 | -## Commentary, getting help | ||
| 60 | - | ||
| 61 | -Actually, I kinda think the whole process for native app communication is quite bad from a developer ergonomics perspective and I have no idea why Google implemented it like that in the first place but it set a precedent and now Firefox is doing it similarly. I am trying to supply some _configuration verification scripts_ but in case everything fails, read the documentation about WebExtensions and native messaging to get back on track: | ||
| 62 | - | ||
| 63 | -* [MDN Web Docs - WebExtensions](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/). | ||
| 64 | -* [Native Messaging API](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging) | ||
| 65 | -* [Native Messaging setup](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging#Setup) | ||
| 43 … | +$ npm run install | ||
| 44 … | +``` | ||
Built with git-ssb-web