diff options
Diffstat (limited to 'toolkit/components/extensions/docs/wiring_up_new_webidl_bindings.rst')
| -rw-r--r-- | toolkit/components/extensions/docs/wiring_up_new_webidl_bindings.rst | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/toolkit/components/extensions/docs/wiring_up_new_webidl_bindings.rst b/toolkit/components/extensions/docs/wiring_up_new_webidl_bindings.rst new file mode 100644 index 0000000000..59088d7079 --- /dev/null +++ b/toolkit/components/extensions/docs/wiring_up_new_webidl_bindings.rst @@ -0,0 +1,165 @@ +Wiring up new WebExtensions WebIDL files into mozilla-central +============================================================= + +Add a new entry in ``dom/bindings/Bindings.conf`` +------------------------------------------------- + +New WebIDL bindings should be added as new entries in ``dom/bindings/Bindings.conf``. The new entry should be +added in alphabetic order and nearby the other WebExtensions API bindings already listed in this config file +(look for the ``ExtensionBrowser`` webidl definition and the other existing WebIDL bindings related to the +WebExtensions APIs): + +.. code-block:: + + # WebExtension API + ... + 'ExtensionRuntime': { + 'headerFile': 'mozilla/extensions/ExtensionRuntime.h', + 'nativeType': 'mozilla::extensions::ExtensionRuntime', + }, + +.. warning:: + + `mach build` will fail if the entries in `dom/bindings/Bindings.conf` are not in alphabetic order, + or if the `headerFile` referenced does not exist yet. + +Add a new entry in ``dom/webidl/moz.build`` +------------------------------------------- + +The new ``.webidl`` file has to be also listed in "dom/webidl/moz.build", it should be added in + +- the existing group of ``WEBIDL_FILES`` entries meant specifically for the WebExtensions API bindings +- or in the group of ``PREPROCESSED_WEBIDL_FILES`` entries meant specifically for the WebExtensions + API bindings, **if the generated `.webidl` includes preprocessing macros** (e.g. when part of an API + is not available in all builds, e.g. subset of APIs that are only available in Desktop builds). + +.. code-block:: + + # WebExtensions API. + WEBIDL_FILES += [ + ... + "ExtensionRuntime.webidl" + ... + ] + + PREPROCESSED_WEBIDL_FILES += [ + ... + ] + +.. warning:: + + The group of PREPROCESSED_WERBIDL_FILES meant to list WebExtensions APIs ``.webidl`` files + may not exist yet (one will be added right after the existing `WEBIDL_FILES` when the first + preprocessed `.webidl` will be added). + + +Add new entries in ``toolkit/components/extensions/webidl-api/moz.build`` +------------------------------------------------------------------------- + +The new C++ files for the WebExtensions API binding needs to be added to ``toolkit/components/extensions/webidl-api/moz.build`` +to make them part of the build, The new ``.cpp`` file has to be added into the ``UNIFIED_SOURCES`` group +where the other WebIDL bindings are being listed. Similarly, the new ``.h`` counterpart has to be added to +``EXPORTS.mozilla.extensions`` (which ensures that the header file will be placed into the path set earlier +in ``dom/bindings/Bindings.conf``): + +.. code-block:: + + # WebExtensions API namespaces. + UNIFIED_SOURCES += [ + ... + "ExtensionRuntime.cpp", + ... + ] + + EXPORTS.mozilla.extensions += [ + ... + "ExtensionRuntime.h", + ... + ] + +Wiring up the new API into ``dom/webidl/ExtensionBrowser.webidl`` +----------------------------------------------------------------- + +To make the new WebIDL bindings part of the ``browser`` global, a new attribute has to be added to +``dom/webidl/ExtensionBrowser.webidl``: + +.. code-block:: + + // `browser.runtime` API namespace. + [Replaceable, SameObject, BinaryName="GetExtensionRuntime", + Func="mozilla::extensions::ExtensionRuntime::IsAllowed"] + readonly attribute ExtensionRuntime runtime; + +.. note:: + ``chrome`` is defined as an alias of the ``browser`` global, and so by adding the new attribute + into ``ExtensionBrowser` the same attribute will also be available in the ``chrome`` global. + Unlike the "Privileged JS"-based WebExtensions API, the ``chrome`` and ``browser`` APIs are + exactly the same and a the async methods return a Promise if no callback has been passed + (similarly to Safari versions where the WebExtensions APIs are supported). + +The additional attribute added into ``ExtensionBrowser.webidl`` will require some addition to the ``ExtensionBrowser`` +C++ class as defined in ``toolkit/components/extensions/webidl-api/ExtensionBrowser.h``: + +- the definition of a new corresponding **public method** (by convention named ``GetExtensionMyNamespace``) +- a ``RefPtr`` as a new **private data member named** (by convention named ``mExtensionMyNamespace``) + +.. code-block:: + + ... + namespace extensions { + + ... + class ExtensionRuntime; + ... + + class ExtensionBrowser final : ... { + ... + RefPtr<ExtensionRuntime> mExtensionRuntime; + ... + + public: + ... + ExtensionRuntime* GetExtensionRuntime(); + } + ... + + +And then in its ``toolkit/components/extensions/webidl-api/ExtensionBrowser.cpp`` counterpart: + +- the implementation of the new public method +- the addition of the new private member data ``RefPtr`` in the ``NS_IMPL_CYCLE_COLLECTION_UNLINK`` + and ``NS_IMPL_CYCLE_COLLECTION_TRAVERSE`` macros + +.. code-block:: + + ... + #include "mozilla/extensions/ExtensionRuntime.h" + ... + NS_IMPL_CYCLE_COLLECTION_UNLINK_BEGIN(ExtensionBrowser) + ... + NS_IMPL_CYCLE_COLLECTION_UNLINK(mExtensionRuntime) + ... + NS_IMPL_CYCLE_COLLECTION_UNLINK_END + + NS_IMPL_CYCLE_COLLECTION_TRAVERSE_BEGIN(ExtensionBrowser) + ... + NS_IMPL_CYCLE_COLLECTION_TRAVERSE(mExtensionRuntime) + ... + NS_IMPL_CYCLE_COLLECTION_TRAVERSE_END + ... + + ExtensionRuntime* ExtensionBrowser::GetExtensionRuntime() { + if (!mExtensionRuntime) { + mExtensionRuntime = new ExtensionRuntime(mGlobal, this); + } + + return mExtensionRuntime + } + +.. warning:: + + Forgetting to add the new ``RefPtr`` into the cycle collection traverse and unlink macros + will not result in a build error, but it will result into a leak. + + Make sure to don't forget to double-check these macros, especially if some tests are failing + because of detected shutdown leaks. |