blob: ea29d6b7b64a315ca180cc68c44d8b6c4f33c658 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
Generating WebIDL definitions from WebExtensions API JSONSchema
===============================================================
In ``toolkit/components/extensions/webidl-api``, a python script named ``GenerateWebIDLBindings.py``
helps to generation of the WebIDL definitions for the WebExtensions API namespaces based on the existing
JSONSchema data.
.. figure:: generate_webidl_from_jsonschema_dataflow.drawio.svg
:alt: Diagram of the GenerateWebIDLBindings.py script data flow
..
This svg diagram has been created using https://app.diagrams.net,
the svg file also includes the source in the drawio format and so
it can be edited more easily by loading it back into app.diagrams.net
and then re-export from there (and include the updated drawio format
content into the exported svg file).
Example: how to execute GenerateWebIDLBindings.py
-------------------------------------------------
As an example, the following shell command generates (or regenerates if one exists) the webidl bindings
for the `runtime` API namespace:
.. code-block:: sh
$ export SCRIPT_DIR="toolkit/components/extensions/webidl-api"
$ mach python $SCRIPT_DIR/GenerateWebIDLBindings.py -- runtime
this command will generates a `.webdil` file named `dom/webidl/ExtensionRuntime.webidl`.
.. warning::
This python script uses some python libraries part of mozilla-central ``mach`` command
and so it has to be executed using ``mach python`` and any command line options that has
to the passed to the ``GenerateWebIDLBindings.py`` script should be passed after the ``--``
one that ends ``mach python`` own command line options.
* If a webidl file with the same name already exist, the python script will ask confirmation and
offer to print a diff of the changes (or just continue without changing the existing webidl file
if the content is exactly the same):
.. code-block::
$ mach python $SCRIPT_DIR/GenerateWebIDLBindings.py -- runtime
Generating webidl definition for 'runtime' => dom/webidl/ExtensionRuntime.webidl
Found existing dom/webidl/ExtensionRuntime.webidl.
(Run again with --overwrite-existing to allow overwriting it automatically)
Overwrite dom/webidl/ExtensionRuntime.webidl? (Yes/No/Diff)
D
--- ExtensionRuntime.webidl--existing
+++ ExtensionRuntime.webidl--updated
@@ -24,6 +24,9 @@
[Exposed=(ServiceWorker), LegacyNoInterfaceObject]
interface ExtensionRuntime {
// API methods.
+
+ [Throws, WebExtensionStub="Async"]
+ any myNewMethod(boolean aBoolParam, optional Function callback);
[Throws, WebExtensionStub="Async"]
any openOptionsPage(optional Function callback);
Overwrite dom/webidl/ExtensionRuntime.webidl? (Yes/No/Diff)
* By convention each WebExtensions API WebIDL binding is expected to be paired with C++ files
named ``ExtensionMyNamespace.h`` and ``ExtensionMyNamespace.cpp`` and located in
``toolkit/components/extensions/webidl-api``:
* if no files with the expected names is found the python script will generate an initial
boilerplate files and will store them in the expected mozilla-central directory.
* The Firefox developers are responsible to fill this initial boilerplate as needed and
to apply the necessary changes (if any) when the webidl definitions are updated because
of changes to the WebExtensions APIs JSONSchema.
``ExtensionWebIDL.conf`` config file
------------------------------------
TODO:
* mention the role of the "webidl generation" script config file in handling
special cases (e.g. mapping types and method stubs)
* notes on desktop-only APIs and API namespaces only partially available on Android
``WebExtensionStub`` WebIDL extended attribute
----------------------------------------------
TODO:
* mention the special webidl extended attribute used in the WebIDL definitions
|
