diff options
Diffstat (limited to 'toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst')
-rw-r--r-- | toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst b/toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst new file mode 100644 index 0000000000..ea29d6b7b6 --- /dev/null +++ b/toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst @@ -0,0 +1,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 |