|
| 1 | +# Developer notes for IPFS Companion |
| 2 | + |
| 3 | +### Table of contents |
| 4 | + |
| 5 | +* [Build from source](#build-from-source) |
| 6 | + * [Clone and install dependencies](#clone-and-install-dependencies) |
| 7 | + * [Build and run in Firefox](#build-and-run-in-firefox) |
| 8 | + * [Build and manually install in Chromium](#build-and-manually-install-in-chromium) |
| 9 | +* [Useful tasks](#useful-tasks) |
| 10 | +* [Other tips](#other-tips) |
| 11 | +* [Using IPFS Companion on Firefox for Android](#using-ipfs-companion-on-firefox-for-android) |
| 12 | + * [Install Firefox for Android](#install-firefox-for-android) |
| 13 | + * [Install IPFS Companion](#install-ipfs-companion) |
| 14 | + * [Hot-deploy over USB](#hot-deploy-over-usb) |
| 15 | + * [Debugging in Firefox for Android](#debugging-in-firefox-for-android) |
| 16 | + * [Further resources](#further-resources) |
| 17 | + |
| 18 | +## Build from source |
| 19 | + |
| 20 | +If you're looking to develop on IPFS Companion, you should build the project from source. You will need [NodeJS](https://nodejs.org/) and [Firefox](https://www.mozilla.org/en-US/firefox/developer/). Make sure `npm` and `firefox` are in your `PATH`. |
| 21 | + |
| 22 | +You can use `yarn` instead of `npm`. We provide `yarn.lock` if you choose to do so. This guide assumes you are using `npm`. |
| 23 | + |
| 24 | +### Clone and install dependencies |
| 25 | + |
| 26 | +First, clone the `ipfs-shipyard/ipfs-companion` [repository](https://github.com/ipfs-shipyard/ipfs-companion): |
| 27 | + |
| 28 | + ```bash |
| 29 | + git clone https://github.com/ipfs-shipyard/ipfs-companion.git |
| 30 | + ``` |
| 31 | + |
| 32 | +To install all dependencies into the `node_modules` directory, execute: |
| 33 | + |
| 34 | +```bash |
| 35 | +npm install |
| 36 | +``` |
| 37 | + |
| 38 | +### Build and run in Firefox |
| 39 | + |
| 40 | +Use this one-stop command to build, test and deploy the add-on to Firefox: |
| 41 | + |
| 42 | +```bash |
| 43 | +npm start # all-in-one |
| 44 | +``` |
| 45 | + |
| 46 | +If you run into issues, you can run each step manually to pinpoint where the process is failing: |
| 47 | + |
| 48 | +```bash |
| 49 | +npm run build # build runs bundle:firefox at the end, so manifest will be ok |
| 50 | +npm run test # test suite |
| 51 | +npm run firefox # spawn new Firefox |
| 52 | +``` |
| 53 | + |
| 54 | +It is also possible to load the extension manually. Enter `about:debugging` in the URL bar, and then click "Load Temporary Add-on" and point it at `add-on/manifest.json`. |
| 55 | + |
| 56 | +### Build and manually install in Chromium |
| 57 | + |
| 58 | +First, clone the repository: |
| 59 | + |
| 60 | + ```bash |
| 61 | + git clone https://github.com/ipfs-shipyard/ipfs-companion.git |
| 62 | + ``` |
| 63 | + |
| 64 | +Then build it manually: |
| 65 | + |
| 66 | +```bash |
| 67 | +npm run build bundle:chromium # last part is important: it overwrites manifest |
| 68 | +``` |
| 69 | + |
| 70 | +Then open `chrome://extensions` in your Chromium-based browser, enable "Developer mode", click "Load unpacked extension..." and point it at the `add-on` folder within your project folder. |
| 71 | + |
| 72 | +| Chrome "unpacked extension" | Firefox "temporary add-on" | |
| 73 | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 74 | +|  |  | |
| 75 | + |
| 76 | + |
| 77 | +## Useful tasks |
| 78 | + |
| 79 | +Each `npm` task can run separately, but most of the time, `dev-build`, `test`, and `fix:lint` are all you need. |
| 80 | + |
| 81 | +- `npm install`: Install all NPM dependencies |
| 82 | +- `npm run build`: Build the add-on (copy external libraries, create `.zip` bundles for Chrome and Firefox) |
| 83 | +- `npm run bundle:chromium`: Overwrite manifest and package a generic, Chromium-compatible version |
| 84 | +- `npm run bundle:brave`: Overwrite manifest and package a Brave-compatible version requesting access to `chrome.sockets` |
| 85 | +- `npm run bundle:firefox`: Overwrite manifest and package a Firefox-compatible version |
| 86 | +- `npm run build:rename-artifacts`: Rename artifacts to include runtimes in filenames |
| 87 | +- `npm run ci`: Run tests and build (with frozen `yarn.lock`) |
| 88 | +- `npm test`: Run the entire test suite |
| 89 | +- `npm run lint`: Read-only check for potential syntax problems (run all linters) |
| 90 | +- `npm run fix:lint`: Try to fix simple syntax problems (run `standard` with `--fix`, etc.) |
| 91 | +- `npm run lint:standard`: Run [Standard](http://standardjs.com) linter ([IPFS JavaScript projects default to standard code style](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md)) |
| 92 | +- `npm run lint:web-ext`: Run [addons-linter](https://github.com/mozilla/addons-linter) shipped with `web-ext` tool |
| 93 | +- `npm run firefox`: Run as temporary add-on in Firefox |
| 94 | +- `npm run chromium`: Run as temporary add-on in Chromium |
| 95 | +- `npm run get-firefox-nightly`: Fetch latest Firefox nightly build to `./firefox/` |
| 96 | +- `npm run firefox:beta:add -- --update-link "https://host/path/to/file.xpi" file.xpi`: Add a manifest entry for new self-hosted beta for Firefox |
| 97 | + |
| 98 | +Release build shortcuts: |
| 99 | + |
| 100 | +- `npm run dev-build`: All-in-one: fast dependency install, build with yarn (updates yarn.lock if needed) |
| 101 | +- `npm run beta-build`: Reproducible beta build in docker with frozen `yarn.lock` |
| 102 | +- `npm run release-build`: Reproducible release build in docker with frozen `yarn.lock` |
| 103 | + |
| 104 | +## Other tips |
| 105 | + |
| 106 | +- You can switch to an alternative Firefox version by overriding your `PATH`: |
| 107 | + |
| 108 | + ```bash |
| 109 | + export PATH="/path/to/alternative/version/of/firefox/:${PATH}" |
| 110 | + ``` |
| 111 | + |
| 112 | +- [Using localization in IPFS Companion](LOCALIZATION-NOTES.md) (running browsers with specific locale, etc) |
| 113 | +- [Testing persistent and restart features (Mozilla)](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Testing_persistent_and_restart_features) |
| 114 | + |
| 115 | +## Using IPFS Companion on Firefox for Android |
| 116 | + |
| 117 | +Firefox for Android is capable of running some of the same extensions as the desktop version. This makes it very useful for experimenting with IPFS. |
| 118 | + |
| 119 | +### Install Firefox for Android |
| 120 | + |
| 121 | +All channels are available at the Google Play Store: |
| 122 | + |
| 123 | +- [Latest stable](https://play.google.com/store/apps/details?id=org.mozilla.firefox&hl=en) |
| 124 | +- [Latest beta](https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta) |
| 125 | + |
| 126 | +### Install IPFS Companion |
| 127 | + |
| 128 | +For full installation instructions, see [`README/#install`](https://github.com/ipfs-shipyard/ipfs-companion#install) in the IPFS Companion repo. |
| 129 | + |
| 130 | +You can also test the latest code locally on an emulator, or via USB on your own device. See below for details. |
| 131 | + |
| 132 | +### Hot-deploy over USB |
| 133 | + |
| 134 | +To run your extension in [Firefox for Android](https://www.mozilla.org/en-US/firefox/mobile/), follow these instructions: |
| 135 | + |
| 136 | +- [Set up your computer and Android emulator or device](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android#Set_up_your_computer_and_Android_emulator_or_device) (enable Developer Mode, USB debugging, etc.) |
| 137 | + |
| 138 | +Build everything, and switch `add-on/manifest.json` to the Fennec profile: |
| 139 | + |
| 140 | +``` |
| 141 | +npm run dev-build |
| 142 | +npm run bundle:fennec |
| 143 | +``` |
| 144 | + |
| 145 | +Then, with your device connected to your development computer, run: |
| 146 | + |
| 147 | +``` |
| 148 | +web-ext run -s add-on --target=firefox-android |
| 149 | +``` |
| 150 | + |
| 151 | +It will list all connected devices with their IDs. If the list is empty, go back to the setup step and try again. |
| 152 | + |
| 153 | +Next, deploy your extension to the specific device: |
| 154 | + |
| 155 | +``` |
| 156 | +web-ext run -s add-on --target=firefox-android --android-device=<device ID> |
| 157 | +``` |
| 158 | + |
| 159 | +The first time you run this command, there may be a popup on your Android device asking if you want to grant access over USB. |
| 160 | + |
| 161 | + |
| 162 | +### Debugging in Firefox for Android |
| 163 | + |
| 164 | +The remote debug port will be printed to the console right after successful deployment: |
| 165 | + |
| 166 | +``` |
| 167 | +You can connect to this Android device on TCP port <debug PORT> |
| 168 | +``` |
| 169 | + |
| 170 | +The fastest way to connect is to open `chrome://devtools/content/framework/connect/connect.xhtml` in Firefox on the same machine you run `web-ext` from. |
| 171 | + |
| 172 | +### Further resources |
| 173 | + |
| 174 | +- [MDN: Developing extensions for Firefox for Android](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android) |
0 commit comments