Skip to content

Latest commit

 

History

History
211 lines (140 loc) · 9.95 KB

DEVELOPER-NOTES.md

File metadata and controls

211 lines (140 loc) · 9.95 KB
Raw

Developer notes for IPFS Companion

Table of contents

Build from source

If you're looking to develop on IPFS Companion, you should build the project from source. You will need NodeJS and Firefox. Make sure npm and firefox are in your PATH.

You can use yarn instead of npm. We provide yarn.lock if you choose to do so. This guide assumes you are using npm.

Clone and install dependencies

First, clone the ipfs-shipyard/ipfs-companion repository:

git clone https://github.com/ipfs-shipyard/ipfs-companion.git

To install all dependencies into the node_modules directory, execute:

npm install

Build and run in Firefox

Use this one-stop command to build, test and deploy the add-on to Firefox:

npm start        # all-in-one

If you run into issues, you can run each step manually to pinpoint where the process is failing:

npm run build    # build runs bundle:firefox at the end, so manifest will be ok
npm run test     # test suite
npm run firefox  # spawn new Firefox

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.

Build and manually install in Chromium

First, clone the repository:

git clone https://github.com/ipfs-shipyard/ipfs-companion.git

Then build it manually:

npm run build bundle:chromium # last part is important: it overwrites manifest

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.

Chrome "unpacked extension" Firefox "temporary add-on"
installing ipfs-companion as an unpacked extension in chrome installing ipfs-companion as a temporary add on in firefox

Run build on file changes

Regular build minifies code and strips source maps. It is possible to run build in the watch mode, which will rebuild a debug version of all changed bundles:

npm run build # do regular build first
npm run watch # watch for new changes

Note: watch is a blocking command, so one needs to run it in a different terminal than firefox or chromium. Press ctrl+c to stop it.

Reproducible build in Docker

Want to ensure prebuilt bundle does not include any additional code?
Don't want to install JS dependencies such as NodeJS and yarn?

Do an isolated build inside of Docker!

Run the following command for ending up with a built extension inside the build/ directory:

npm run release-build

It is an alias for running ci:build script inside of immutable Docker image, which guarantees the same output on all platforms.

Useful tasks

Each npm task can run separately, but most of the time, dev-build, test, and fix:lint are all you need.

  • npm install: Install all NPM dependencies
  • npm run build: Build the add-on (copy external libraries, create .zip bundles for Chrome and Firefox)
  • npm run watch: Rebuild JS/CSS on file changes (run regular build first to ensure everything else is in place)
  • npm run bundle:chromium: Overwrite manifest and package a generic, Chromium-compatible version
  • npm run bundle:brave: Overwrite manifest and package a Brave-compatible version requesting access to chrome.sockets
  • npm run bundle:firefox: Overwrite manifest and package a Firefox-compatible version
  • npm run build:rename-artifacts: Rename artifacts to include runtimes in filenames
  • npm run ci: Run tests and build (with frozen yarn.lock)
  • npm test: Run the entire test suite
  • npm run lint: Read-only check for potential syntax problems (run all linters)
  • npm run fix:lint: Try to fix simple syntax problems (run standard with --fix, etc.)
  • npm run lint:standard: Run Standard linter (IPFS JavaScript projects default to standard code style)
  • npm run lint:web-ext: Run addons-linter shipped with web-ext tool
  • npm run firefox: Run as temporary add-on in Firefox
  • npm run firefox:nightly: Run as temporary add-on in Firefox Nightly (uses one in ./firefox/, see get-firefox-nightly below)
  • npm run chromium: Run as temporary add-on in Chromium
  • npm run get-firefox-nightly: Fetch latest Firefox nightly build to ./firefox/
  • 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

Release build shortcuts:

  • npm run dev-build: All-in-one: fast dependency install, build with yarn (updates yarn.lock if needed)
  • npm run beta-build: Reproducible beta build in docker with frozen yarn.lock
  • npm run release-build: Reproducible release build in docker with frozen yarn.lock

Other tips

Legacy Firefox (< 53) and XUL-compatible browsers

Legacy versions 1.x.x were based on currently deprecated Add-On SDK (Firefox-only).
While it is not maintained any more, one can inspect, build, and install it using codebase from legacy-sdk branch. For historical background on the rewrite, see Issue #20: Move to WebExtensions.

Using IPFS Companion on Firefox for Android

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.

Install Firefox for Android

All channels are available at the Google Play Store:

Install IPFS Companion

For full installation instructions, see README/#install in the IPFS Companion repo.

You can also test the latest code locally on an emulator, or via USB on your own device. See below for details.

Hot-deploy over USB

To run your extension in Firefox for Android, follow these instructions:

Build everything, and switch add-on/manifest.json to the Firefox profile:

npm run dev-build
npm run bundle:firefox

Then, with your device connected to your development computer, run:

web-ext run -s add-on --target=firefox-android

It will list all connected devices with their IDs. If the list is empty, go back to the setup step and try again.

Next, deploy your extension to the specific device:

web-ext run -s add-on --target=firefox-android --android-device=<device ID>

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.

Debugging in Firefox for Android

The remote debug port will be printed to the console right after successful deployment:

You can connect to this Android device on TCP port <debug PORT>

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.

Further resources