X-Git-Url: https://git.r.bdr.sh/rbdr/junction/blobdiff_plain/ec4adc33ec00dfe4a5720a13551428aaddaf72d9..a878ac9416129138aba0be7ee3f202a6d8c972f1:/README.md?ds=inline

diff --git a/README.md b/README.md
index 44f490d..ccd9b12 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,97 @@
 # Junction
 
-Connect people through any URL
+Connect people through any URL.
 
-## Extension
+Junction is a web extension for Firefox, Chrome and Safari that lets you start
+an audio call at any URL.
 
-First, make sure to build the plugin. From the extension's root you can call:
+## Building
+
+Running `make` or `make package` will regenerate the content script, and
+package the extension for all browsers in the `./build/` directory with
+the following outputs:
+
+- `junction.xpi`: The firefox extension
+- `junction.zip`: The chrome extension
+- `Junction.app`: The safari extension app
+
+## Developing
+
+The project is divided into three main parts:
+
+- `server`: A server that handles message passing to establish the WebRTC
+  connections.
+- `extension`: The main code of the extension itself.
+- `safari`: The safari app, it wraps the extension using symlinks.
+
+### Dependencies
+
+- `make` to run the build commands. It's included in `macos`
+- `xcode` to build the safari extension. Can be downloaded from the
+  [apple developer portal][xcode-download].
+- `node` and `pnpm` to build the extension, and if you want to run the server
+  directly. Node can be installed via brew with `brew install node`, or with
+  a version manager like [asdf][asdf]. For `pnpm` check the [website][pnpm].
+- `podman` and `podman-compose` if you want to run the server as a container.
+  Both can be installed with homebrew `brew install podman podman-compose`
+- `prettier` to format Javascript, JSON, Yaml, and Markdown. Will automatically
+  install when running `make format`.
+- `xcbeautify` to format swift. Can be installed with homebrew
+  `brew install xcbeautify`
+
+If you're running macos and using homebrew, you can install them all with
+`make prepare-environment`.
+
+### Server
+
+The server is a socket.io server that relays messages between peers to help
+establish a WebRTC connection.
+
+#### Configuration
+
+You can use environment variables to control the server.
+
+- `JUNCTION_SERVER_PORT` which port to listen on. Defaults to `8000`.
+
+### Extension
+
+The extension uses WebExtension manifest v2 and is compatible with Firefox,
+Chrome and Safari.
+
+You can build all extensions using `make` in the root of the directory.
+
+If you want to run manually then you can run `pnpm install` from the
+`extension` folder to install dependencies, and `pnpm build` to generate the
+content script.
 
 ```
 $ pnpm install && pnpm build
 ```
 
-### Testing on Firefox
+#### Testing on Firefox
 
 In order to test on firefox, first go to `about:debugging`, then click
 on the `This Firefox` option. Then click on `Load Temporary Add-On` and
-point the browser to the `extension/manifest.json` file.
+point the browser to the `build/junction.xpi` file if you're using `make`, or
+`extension/manifest.json` file if you're testing without packaging.
 
-This will enable the extension and will allow you to use the inspector to debug.
+This will enable the extension and will allow you to use the inspector to
+debug.
 
-### Testing on Chrome
+#### Testing on Chrome
 
 In order to test on chrome, first go to `chrome://extensions/`. Make sure
-`Developer mode` is enabled. Then click `Load Unpacked` and point the browser
-to the `extension` directory.
+`Developer mode` is enabled. You can drag the `build/junction.zip` file or
+click `Load Unpacked` and point the browser to the `extension` directory.
+
+#### Testing on Safari
+
+Open `Junction.app` and then enable the extension in Safari.
+
+### Formatting
 
-### Packaging
+Running `make format` will format the code with prettify and xcbeautify
 
-The makefile includes scripts to create a distributable package. `make package`
-should generate all supported files in the `build/` directory.
+[xcode-download]: https://developer.apple.com/xcode/resources/
+[asdf]: https://asdf-vm.com/
+[pnpm]: https://pnpm.io/installation