Skip to content

Latest commit

 

History

History
303 lines (203 loc) · 11.1 KB

DEVELOPER-NOTES.md

File metadata and controls

303 lines (203 loc) · 11.1 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.

Clone and install dependencies

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

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

Then, run this all-in-one dev build, which includes installing dependencies into the node_modules directory:

npm run dev-build

Build and run in Firefox

Use this one-stop command to build, test and deploy the add-on in 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:

  1. Enter about:debugging in the address bar
  2. Click "This Firefox" in the left nav
  3. Click "Load Temporary Add-on..."
  4. Pick the file add-on/manifest.json

Build and run in Chromium

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

npm run dev-build chromium        # all-in-one

You can also build it to manually install:

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

Then load the extension manually:

  1. Enter chrome://extensions in the address bar
  2. Enable "Developer mode" using the toggle in the top right of the page
  3. Click "Load unpacked"
  4. Pick the directory add-on

Run build on file changes

The regular run build command minifies code and strips source maps. It is possible to build in 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 run dev-build: Fast dependency install, build with yarn (updates yarn.lock if needed)
  • npm run dev-build firefox: All-in-one for Firefox: fast dependency install, build with yarn, run as temporary add-on in Firefox
  • npm run dev-build chromium: All-in-one for Chromium: fast dependency install, build with yarn, run as temporary add-on in Chromium
  • 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 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

Release build shortcuts:

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

E2E tests:

  • npm run compose:e2e:prepare: Pull and build docker images for e2e tests
  • npm run compose:e2e:up: Start e2e test docker environment
  • npm run compose:e2e:test: Run e2e tests in the docker environment
  • npm run compose:e2e:down: Stop e2e test docker environment

Running E2E tests

E2E tests are run in a docker environment, so you need to have docker installed.

Preparing extension builds

You can run the tests against either release or dev builds of the extension.

To download release builds of the extension, run:

./ci/e2e/download-release-builds.sh

NOTE: When using release builds, you can control the version of the extension by setting the IPFS_COMPANION_VERSION environment variable:

export IPFS_COMPANION_VERSION=x.y.z

To build dev versions of the extension, run:

npm run build

or (to perform the build inside a docker container):

npm run release-build

Preparing the docker environment

You need to pull docker images for Kubo, Chromium and Firefox before running the tests.

You also need to build the docker image containing the e2e tests.

To do all of this, run:

npm run compose:e2e:prepare

NOTE: You can control the versions of Kubo, Chromium and Firefox by setting the following environment variables:

export KUBO_VERSION=x.y.z
export CHROMIUM_VERSION=x.y.z
export FIREFOX_VERSION=x.y.z

IMPORTANT: If you are running the tests on a ARM machine, you need to use a different Chromium image. To do this, run:

export CHROMIUM_IMAGE=seleniarm/standalone-chromium
export FIREFOX_IMAGE=seleniarm/standalone-firefox

Running the tests

To run the tests, run:

npm run compose:e2e:test

NOTE: You can control whether the browsers operate in headless mode as follows:

export TEST_HEADLESS=true

Stopping the docker environment

To stop the docker environment, run:

npm run compose:e2e:down

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