summaryrefslogtreecommitdiffstats
path: root/dom/bindings/docs
diff options
context:
space:
mode:
Diffstat (limited to 'dom/bindings/docs')
-rw-r--r--dom/bindings/docs/index.rst124
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``.