dom/bindings/docs/index.rst@6474c204b198
dom/bindings/docs/index.rst
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 .. _webidl:
3 ======
4 WebIDL
5 ======
7 WebIDL describes interfaces web browsers are supposed to implement.
9 The interaction between WebIDL and the build system is somewhat complex.
10 This document will attempt to explain how it all works.
12 Overview
13 ========
15 ``.webidl`` files throughout the tree define interfaces the browser
16 implements. Since Gecko/Firefox is implemented in C++, there is a
17 mechanism to convert these interfaces and associated metadata to
18 C++ code. That's where the build system comes into play.
20 All the code for interacting with ``.webidl`` files lives under
21 ``dom/bindings``. There is code in the build system to deal with
22 WebIDLs explicitly.
24 WebIDL source file flavors
25 ==========================
27 Not all ``.webidl`` files are created equal! There are several flavors,
28 each represented by a separate symbol from :ref:`mozbuild_symbols`.
30 WEBIDL_FILES
31 Refers to regular/static ``.webidl`` files. Most WebIDL interfaces
32 are defined this way.
34 GENERATED_EVENTS_WEBIDL_FILES
35 In addition to generating a binding, these ``.webidl`` files also
36 generate a source file implementing the event object in C++
38 PREPROCESSED_WEBIDL_FILES
39 The ``.webidl`` files are generated by preprocessing an input file.
40 They otherwise behave like *WEBIDL_FILES*.
42 TEST_WEBIDL_FILES
43 Like *WEBIDL_FILES* but the interfaces are for testing only and
44 aren't shipped with the browser.
46 PREPROCESSED_TEST_WEBIDL_FILES
47 Like *TEST_WEBIDL_FILES* except the ``.webidl`` is obtained via
48 preprocessing, much like *PREPROCESSED_WEBIDL_FILES*.
50 GENERATED_WEBIDL_FILES
51 The ``.webidl`` for these is obtained through an *external*
52 mechanism. Typically there are custom build rules for producing these
53 files.
55 Producing C++ code
56 ==================
58 The most complicated part about WebIDLs is the process by which
59 ``.webidl`` files are converted into C++.
61 This process is handled by code in the :py:mod:`mozwebidlcodegen`
62 package. :py:class:`mozwebidlcodegen.WebIDLCodegenManager` is
63 specifically where you want to look for how code generation is
64 performed. This includes complex dependency management.
66 Requirements
67 ============
69 This section aims to document the build and developer workflow requirements
70 for WebIDL.
72 Parser unit tests
73 There are parser tests provided by ``dom/bindings/parser/runtests.py``
74 that should run as part of ``make check``. There must be a mechanism
75 to run the tests in *human* mode so they output friendly error
76 messages.
78 The current mechanism for this is ``mach webidl-parser-test``.
80 Mochitests
81 There are various mochitests under ``dom/bindings/test``. They should
82 be runnable through the standard mechanisms.
84 Working with test interfaces
85 ``TestExampleGenBinding.cpp`` calls into methods from the
86 ``TestExampleInterface`` and ``TestExampleProxyInterface`` interfaces.
87 These interfaces need to be generated as part of the build. These
88 interfaces should not be exported or packaged.
90 There is a ``compiletests`` make target in ``dom/bindings`` that
91 isn't part of the build that facilitates turnkey code generation
92 and test file compilation.
94 Minimal rebuilds
95 Reprocessing every output for every change is expensive. So we don't
96 inconvenience people changing ``.webidl`` files, the build system
97 should only perform a minimal rebuild when sources change.
99 This logic is mostly all handled in
100 :py:class:`mozwebidlcodegen.WebIDLCodegenManager`. The unit tests for
101 that Python code should adequately test typical rebuild scenarios.
103 Bug 940469 tracks making the existing implementation better.
105 Explicit method for performing codegen
106 There needs to be an explicit method for invoking code generation.
107 It needs to cover regular and test files.
109 This is implemented via ``make export`` in ``dom/bindings``.
111 No-op binding generation should be fast
112 So developers touching ``.webidl`` files are not inconvenienced,
113 no-op binding generation should be fast. Watch out for the build system
114 processing large dependency files it doesn't need in order to perform
115 code generation.
117 Ability to generate example files
118 *Any* interface can have example ``.h``/``.cpp`` files generated.
119 There must be a mechanism to facilitate this.
121 This is currently facilitated through ``mach webidl-example``. e.g.
122 ``mach webidl-example HTMLStyleElement``.
