diff options
Diffstat (limited to '')
| -rw-r--r-- | dom/bindings/docs/index.rst | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/dom/bindings/docs/index.rst b/dom/bindings/docs/index.rst new file mode 100644 index 0000000000..d47d4c9c68 --- /dev/null +++ b/dom/bindings/docs/index.rst @@ -0,0 +1,124 @@ +.. _webidl: + +====== +WebIDL +====== + +WebIDL describes interfaces web browsers are supposed to implement. + +The interaction between WebIDL and the build system is somewhat complex. +This document will attempt to explain how it all works. + +Overview +======== + +``.webidl`` files throughout the tree define interfaces the browser +implements. Since Gecko/Firefox is implemented in C++, there is a +mechanism to convert these interfaces and associated metadata to +C++ code. That's where the build system comes into play. + +All the code for interacting with ``.webidl`` files lives under +``dom/bindings``. There is code in the build system to deal with +WebIDLs explicitly. + +WebIDL source file flavors +========================== + +Not all ``.webidl`` files are created equal! There are several flavors, +each represented by a separate symbol from :ref:`mozbuild_symbols`. + +WEBIDL_FILES + Refers to regular/static ``.webidl`` files. Most WebIDL interfaces + are defined this way. + +GENERATED_EVENTS_WEBIDL_FILES + In addition to generating a binding, these ``.webidl`` files also + generate a source file implementing the event object in C++ + +PREPROCESSED_WEBIDL_FILES + The ``.webidl`` files are generated by preprocessing an input file. + They otherwise behave like *WEBIDL_FILES*. + +TEST_WEBIDL_FILES + Like *WEBIDL_FILES* but the interfaces are for testing only and + aren't shipped with the browser. + +PREPROCESSED_TEST_WEBIDL_FILES + Like *TEST_WEBIDL_FILES* except the ``.webidl`` is obtained via + preprocessing, much like *PREPROCESSED_WEBIDL_FILES*. + +GENERATED_WEBIDL_FILES + The ``.webidl`` for these is obtained through an *external* + mechanism. Typically there are custom build rules for producing these + files. + +Producing C++ code +================== + +The most complicated part about WebIDLs is the process by which +``.webidl`` files are converted into C++. + +This process is handled by code in the :py:mod:`mozwebidlcodegen` +package. :py:class:`mozwebidlcodegen.WebIDLCodegenManager` is +specifically where you want to look for how code generation is +performed. This includes complex dependency management. + +Requirements +============ + +This section aims to document the build and developer workflow requirements +for WebIDL. + +Parser unit tests + There are parser tests provided by ``dom/bindings/parser/runtests.py`` + that should run as part of ``make check``. There must be a mechanism + to run the tests in *human* mode so they output friendly error + messages. + + The current mechanism for this is ``mach webidl-parser-test``. + +Mochitests + There are various mochitests under ``dom/bindings/test``. They should + be runnable through the standard mechanisms. + +Working with test interfaces + ``TestExampleGenBinding.cpp`` calls into methods from the + ``TestExampleInterface``, ``TestExampleProxyInterface``, + ``TestExampleThrowingConstructorInterface``, + and ``TestExampleWorkerInterface`` interfaces. + These interfaces need to be generated as part of the build. These + interfaces should not be exported or packaged. + + There is a ``compiletests`` make target in ``dom/bindings`` that + isn't part of the build that facilitates turnkey code generation + and test file compilation. + +Minimal rebuilds + Reprocessing every output for every change is expensive. So we don't + inconvenience people changing ``.webidl`` files, the build system + should only perform a minimal rebuild when sources change. + + This logic is mostly all handled in + :py:class:`mozwebidlcodegen.WebIDLCodegenManager`. The unit tests for + that Python code should adequately test typical rebuild scenarios. + + Bug 940469 tracks making the existing implementation better. + +Explicit method for performing codegen + There needs to be an explicit method for invoking code generation. + It needs to cover regular and test files. + + This is implemented via ``make export`` in ``dom/bindings``. + +No-op binding generation should be fast + So developers touching ``.webidl`` files are not inconvenienced, + no-op binding generation should be fast. Watch out for the build system + processing large dependency files it doesn't need in order to perform + code generation. + +Ability to generate example files + *Any* interface can have example ``.h``/``.cpp`` files generated. + There must be a mechanism to facilitate this. + + This is currently facilitated through ``mach webidl-example``. e.g. + ``mach webidl-example HTMLStyleElement``. |