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):

# 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).

# 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):

# 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:

// `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)

...
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

...
#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.