47
edits
WebExtensions/Hacking: Difference between revisions
Add link to WebExtension-specific Try server article
(→Vim: Make path more generic) |
(Add link to WebExtension-specific Try server article) |
||
| (7 intermediate revisions by 3 users not shown) | |||
| Line 20: | Line 20: | ||
ESLint will enforce most of these rules. | ESLint will enforce most of these rules. | ||
== Code Guidelines == | |||
For Chrome APIs we'll support the callback interface to maintain compatibility. For new APIs, not Chrome ones, we'll use the promise interface to all APIs. See the [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API#Callbacks_and_promises MDN docs] for the difference. | |||
== Checking your code with ESLint == | == Checking your code with ESLint == | ||
| Line 53: | Line 57: | ||
The following assumes that you use the [https://github.com/VundleVim/Vundle.vim Vundle package manager]. It should be easy enough to adapt to any other package manager you happen to prefer, though. | The following assumes that you use the [https://github.com/VundleVim/Vundle.vim Vundle package manager]. It should be easy enough to adapt to any other package manager you happen to prefer, though. | ||
<code>mach eslint --setup</code> installs a specific ESLint version and some ESLint plugins to a subdirectory of the repository. | <code>mach eslint --setup</code> installs a specific ESLint version and some ESLint plugins to a subdirectory of the repository ([https://bugzilla.mozilla.org/show_bug.cgi?id=1305023 changed in Firefox 55]). | ||
You should configure Syntastic roughly as follows (change <code>/path/to/mozilla-central</code> as needed): | You should configure Syntastic roughly as follows (change <code>/path/to/mozilla-central</code> as needed): | ||
| Line 68: | Line 72: | ||
\ if stridx(expand("%:p"), "/mozilla-central/") != -1 | | \ if stridx(expand("%:p"), "/mozilla-central/") != -1 | | ||
\ let b:syntastic_checkers = ['eslint'] | | \ let b:syntastic_checkers = ['eslint'] | | ||
\ let b:syntastic_eslint_exec = '/path/to/mozilla-central | \ let b:syntastic_eslint_exec = '/path/to/mozilla-central/node_modules/.bin/eslint' | | ||
\ let b:syntastic_html_eslint_args = ['--plugin', 'html'] | | \ let b:syntastic_html_eslint_args = ['--plugin', 'html'] | | ||
\ endif | \ endif | ||
| Line 103: | Line 107: | ||
;xpcshell tests | ;xpcshell tests | ||
: These reside under <code>toolkit/components/extensions/test/xpcshell/</code>, and are used to test low-level modules which do not require a browser UI, including those under <code>toolkit/modules/addons/</code>, <code>toolkit/components/utils/simpleServices.js</code>, and various pieces of C++ code. | : These reside under <code>toolkit/components/extensions/test/xpcshell/</code>, and are used to test low-level modules which do not require a browser UI, including those under <code>toolkit/modules/addons/</code>, <code>toolkit/components/utils/simpleServices.js</code>, and various pieces of C++ code. | ||
[[WebExtensions/Try_Server]] has more information about using the try server to test WebExtension code. | |||
=== Test tag === | |||
All tests in WebExtensions are [https://bugzilla.mozilla.org/show_bug.cgi?id=1296888 now tagged] with the tag: <code>webextensions</code>, so you can pass the <code>--tag</code> argument to <code>mochitest</code>, <code>xpcshell-test</code> and the [http://trychooser.pub.build.mozilla.org/ try server syntax]. | |||
=== Code coverage tests === | === Code coverage tests === | ||
| Line 121: | Line 131: | ||
The above results are generated using [https://people.mozilla.org/~kmaglione/webext-coverage.patch this patch], which could generously be described as a fairly gross hack. If you'd like to run the tests yourself, you can do so with something like the following: | The above results are generated using [https://people.mozilla.org/~kmaglione/webext-coverage.patch this patch], which could generously be described as a fairly gross hack. If you'd like to run the tests yourself, you can do so with something like the following: | ||
# Install the | # Install the Istanbul code coverage tool | ||
npm install -g istanbul | npm install -g istanbul | ||
| Line 162: | Line 172: | ||
Each API module must be explicitly registered, in order to be loaded. It must also register a schema if it exports any APIs to extensions. | Each API module must be explicitly registered, in order to be loaded. It must also register a schema if it exports any APIs to extensions. | ||
Generic APIs | Starting from Firefox 50 ([https://bugzilla.mozilla.org/1285063 Bug 1285063], [https://hg.mozilla.org/mozilla-central/rev/e9ca8dc4b42e hg commit e9ca8dc4b42e]) all the APIs schema and <code>ext-*.js</code> files must be registered to the category manager through one of the following manifest files: | ||
* [https://dxr.mozilla.org/mozilla-central/source/toolkit/components/extensions/extensions-toolkit.manifest toolkit/components/extensions/extensions-toolkit.manifest], for Generic APIs registered at toolkit level | |||
* [https://dxr.mozilla.org/mozilla-central/source/browser/components/extensions/extensions-browser.manifest browser/components/extensions/extensions-browser.manifest], for Firefox desktop APIs | |||
* [https://dxr.mozilla.org/mozilla-central/source/mobile/android/components/extensions/extensions-mobile.manifest mobile/android/components/extensions/extensions-mobile.manifest], for Firefox for Android APIs | |||
As an example, here is a snippet of the <code>extension-toolkit.manifest</code>: | |||
# scripts | |||
category webextension-scripts alarms chrome://extensions/content/ext-alarms.js | |||
... | |||
# schemas | |||
category webextension-schemas alarms chrome://extensions/content/schemas/alarms.json | |||
In previous Firefox versions, schemas and <code>ext-*.js</code> files were statically | |||
registered through <code>Extension.jsm</code> and <code>nsBrowserGlue.js</code> source | |||
files: | |||
Generic APIs were registered in <code>Extension.jsm</code> as follows: | |||
ExtensionManagement.registerScript("chrome://extensions/content/ext-foobar.js"); | ExtensionManagement.registerScript("chrome://extensions/content/ext-foobar.js"); | ||
| Line 168: | Line 197: | ||
ExtensionManagement.registerSchema("chrome://extensions/content/schemas/foobar.json"); | ExtensionManagement.registerSchema("chrome://extensions/content/schemas/foobar.json"); | ||
Firefox desktop APIs | Firefox desktop APIs were registered in [https://dxr.mozilla.org/mozilla-central/source/browser/components/nsBrowserGlue.js nsBrowserGlue.js]: | ||
ExtensionManagement.registerScript("chrome://browser/content/ext-bazquux.js"); | ExtensionManagement.registerScript("chrome://browser/content/ext-bazquux.js"); | ||
ExtensionManagement.registerSchema("chrome://browser/content/schemas/bazquux.json"); | ExtensionManagement.registerSchema("chrome://browser/content/schemas/bazquux.json"); | ||
=== Permission strings === | |||
The strings for permissions can be found in [https://dxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/browser.properties browser.properties]. | |||
If you add an API that requires permissions, then you'll need to make sure the corresponding permission strings are also landed. | |||