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

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

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

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

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

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

```cpp
...
#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.
:::