-
Notifications
You must be signed in to change notification settings - Fork 324
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: make Preferences link to docs site (#871)
Co-authored-by: Jessica Schilling <jessica@protocol.ai> Co-authored-by: Marcin Rataj <lidel@lidel.org>
- Loading branch information
1 parent
793bd6c
commit eda02e7
Showing
22 changed files
with
248 additions
and
631 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,174 @@ | ||
| # Developer notes for IPFS Companion | ||
|
|
||
| ### Table of contents | ||
|
|
||
| * [Build from source](#build-from-source) | ||
| * [Clone and install dependencies](#clone-and-install-dependencies) | ||
| * [Build and run in Firefox](#build-and-run-in-firefox) | ||
| * [Build and manually install in Chromium](#build-and-manually-install-in-chromium) | ||
| * [Useful tasks](#useful-tasks) | ||
| * [Other tips](#other-tips) | ||
| * [Using IPFS Companion on Firefox for Android](#using-ipfs-companion-on-firefox-for-android) | ||
| * [Install Firefox for Android](#install-firefox-for-android) | ||
| * [Install IPFS Companion](#install-ipfs-companion) | ||
| * [Hot-deploy over USB](#hot-deploy-over-usb) | ||
| * [Debugging in Firefox for Android](#debugging-in-firefox-for-android) | ||
| * [Further resources](#further-resources) | ||
|
|
||
| ## Build from source | ||
|
|
||
| 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`. | ||
|
|
||
| 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](https://github.com/ipfs-shipyard/ipfs-companion): | ||
|
|
||
| ```bash | ||
| git clone https://github.com/ipfs-shipyard/ipfs-companion.git | ||
| ``` | ||
|
|
||
| To install all dependencies into the `node_modules` directory, execute: | ||
|
|
||
| ```bash | ||
| npm install | ||
| ``` | ||
|
|
||
| ### Build and run in Firefox | ||
|
|
||
| Use this one-stop command to build, test and deploy the add-on to Firefox: | ||
|
|
||
| ```bash | ||
| npm start # all-in-one | ||
| ``` | ||
|
|
||
| If you run into issues, you can run each step manually to pinpoint where the process is failing: | ||
|
|
||
| ```bash | ||
| 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: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/ipfs-shipyard/ipfs-companion.git | ||
| ``` | ||
|
|
||
| Then build it manually: | ||
|
|
||
| ```bash | ||
| 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" | | ||
| |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| |  |  | | ||
|
|
||
|
|
||
| ## 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 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](http://standardjs.com) linter ([IPFS JavaScript projects default to standard code style](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md)) | ||
| - `npm run lint:web-ext`: Run [addons-linter](https://github.com/mozilla/addons-linter) shipped with `web-ext` tool | ||
| - `npm run firefox`: Run as temporary add-on in Firefox | ||
| - `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 | ||
|
|
||
| - You can switch to an alternative Firefox version by overriding your `PATH`: | ||
|
|
||
| ```bash | ||
| export PATH="/path/to/alternative/version/of/firefox/:${PATH}" | ||
| ``` | ||
|
|
||
| - [Using localization in IPFS Companion](LOCALIZATION-NOTES.md) (running browsers with specific locale, etc) | ||
| - [Testing persistent and restart features (Mozilla)](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Testing_persistent_and_restart_features) | ||
|
|
||
| ## 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: | ||
|
|
||
| - [Latest stable](https://play.google.com/store/apps/details?id=org.mozilla.firefox&hl=en) | ||
| - [Latest beta](https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta) | ||
|
|
||
| ### Install IPFS Companion | ||
|
|
||
| For full installation instructions, see [`README/#install`](https://github.com/ipfs-shipyard/ipfs-companion#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](https://www.mozilla.org/en-US/firefox/mobile/), follow these instructions: | ||
|
|
||
| - [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.) | ||
|
|
||
| Build everything, and switch `add-on/manifest.json` to the Fennec profile: | ||
|
|
||
| ``` | ||
| npm run dev-build | ||
| npm run bundle:fennec | ||
| ``` | ||
|
|
||
| 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 | ||
|
|
||
| - [MDN: Developing extensions for Firefox for Android](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Localization in IPFS Companion | ||
|
|
||
| ### Table of contents | ||
|
|
||
| * [Running Chrome with a specific locale](#running-chrome-with-a-specific-locale) | ||
| * [Running Firefox with a specific locale](#running-firefox-with-a-specific-locale) | ||
| * [Contributing translations](#contributing-translations) | ||
|
|
||
| IPFS Companion supports running in specific locales, with translations provided by the community via Transifex. | ||
|
|
||
| ## Running Chrome with a specific locale | ||
|
|
||
| Chrome comes with locales out of the box, so it is enough to set the proper env: | ||
|
|
||
| ```go | ||
| LANGUAGE=pl chromium --user-data-dir=`mktemp -d` | ||
| ``` | ||
|
|
||
| ### Further resources | ||
|
|
||
| - [Language Codes in Chromium Project](https://src.chromium.org/viewvc/chrome/trunk/src/third_party/cld/languages/internal/languages.cc) | ||
|
|
||
| ## Running Firefox with a specific locale | ||
|
|
||
| Unless you've installed a locale-specific build, Firefox will have English only. If your build already has the locale you are interested in, skip step #2. | ||
|
|
||
| 1. Set `intl.locale.requested` in `about:config` or the command line via: | ||
|
|
||
| ```bash | ||
| web-ext run --pref intl.locale.requested=pl | ||
| ``` | ||
|
|
||
| 2. Install your language pack from https://addons.mozilla.org/firefox/language-tools/ | ||
| 3. Reload the browser extension; it should detect your new locale | ||
|
|
||
| ### Further resources | ||
|
|
||
| - [Mozilla: Use Firefox in another language](https://support.mozilla.org/en-US/kb/use-firefox-interface-other-languages-language-pack#w_how-to-change-the-language-of-the-user-interface) | ||
| - [Mozilla: Locale Codes](https://wiki.mozilla.org/L10n:Locale_Codes) | ||
|
|
||
| ## Contributing translations | ||
|
|
||
| Internationalization in IPFS Companion (and all IPFS-related projects) depends on the contributions of the community. You can give back by contributing translations in your language(s)! Go to the [IPFS Companion Transifex page](https://www.transifex.com/ipfs/ipfs-companion/), send a request to join a specific language team, and start translating. You can also download raw files from Transifex, translate them in your own editor/tool, and then upload them back there, but many people prefer using the simple and friendly Transifex GUI. | ||
|
|
||
| If your language is not present in `add-on/_locales` yet, but is supported by mainstream browsers, please create a [new issue](https://github.com/ipfs/ipfs-companion/issues/new) requesting it. | ||
|
|
||
| Don't worry if GitHub does not immediately reflect translations added at Transifex: New translations are merged manually before every release. Locale files at GitHub are often behind what is already translated at Transifex. It is a good idea to keep Transifex email notifications enabled to be notified about new strings to translate. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1 @@ | ||
| # IPFS Companion | ||
|
|
||
| These pages are scheduled to be moved to [IPFS Docs](https://docs-beta.ipfs.io). | ||
| Content present in this directory was moved to [IPFS Docs](https://docs-beta.ipfs.io). |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.