The Tor Browser / file comparison
comparison: dom/bindings/docs/index.rst
dom/bindings/docs/index.rst
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:8550e0b52efa |
|---|---|
| 1 .. _webidl: | |
| 2 | |
| 3 ====== | |
| 4 WebIDL | |
| 5 ====== | |
| 6 | |
| 7 WebIDL describes interfaces web browsers are supposed to implement. | |
| 8 | |
| 9 The interaction between WebIDL and the build system is somewhat complex. | |
| 10 This document will attempt to explain how it all works. | |
| 11 | |
| 12 Overview | |
| 13 ======== | |
| 14 | |
| 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. | |
| 19 | |
| 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. | |
| 23 | |
| 24 WebIDL source file flavors | |
| 25 ========================== | |
| 26 | |
| 27 Not all ``.webidl`` files are created equal! There are several flavors, | |
| 28 each represented by a separate symbol from :ref:`mozbuild_symbols`. | |
| 29 | |
| 30 WEBIDL_FILES | |
| 31 Refers to regular/static ``.webidl`` files. Most WebIDL interfaces | |
| 32 are defined this way. | |
| 33 | |
| 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++ | |
| 37 | |
| 38 PREPROCESSED_WEBIDL_FILES | |
| 39 The ``.webidl`` files are generated by preprocessing an input file. | |
| 40 They otherwise behave like *WEBIDL_FILES*. | |
| 41 | |
| 42 TEST_WEBIDL_FILES | |
| 43 Like *WEBIDL_FILES* but the interfaces are for testing only and | |
| 44 aren't shipped with the browser. | |
| 45 | |
| 46 PREPROCESSED_TEST_WEBIDL_FILES | |
| 47 Like *TEST_WEBIDL_FILES* except the ``.webidl`` is obtained via | |
| 48 preprocessing, much like *PREPROCESSED_WEBIDL_FILES*. | |
| 49 | |
| 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. | |
| 54 | |
| 55 Producing C++ code | |
| 56 ================== | |
| 57 | |
| 58 The most complicated part about WebIDLs is the process by which | |
| 59 ``.webidl`` files are converted into C++. | |
| 60 | |
| 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. | |
| 65 | |
| 66 Requirements | |
| 67 ============ | |
| 68 | |
| 69 This section aims to document the build and developer workflow requirements | |
| 70 for WebIDL. | |
| 71 | |
| 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. | |
| 77 | |
| 78 The current mechanism for this is ``mach webidl-parser-test``. | |
| 79 | |
| 80 Mochitests | |
| 81 There are various mochitests under ``dom/bindings/test``. They should | |
| 82 be runnable through the standard mechanisms. | |
| 83 | |
| 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. | |
| 89 | |
| 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. | |
| 93 | |
| 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. | |
| 98 | |
| 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. | |
| 102 | |
| 103 Bug 940469 tracks making the existing implementation better. | |
| 104 | |
| 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. | |
| 108 | |
| 109 This is implemented via ``make export`` in ``dom/bindings``. | |
| 110 | |
| 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. | |
| 116 | |
| 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. | |
| 120 | |
| 121 This is currently facilitated through ``mach webidl-example``. e.g. | |
| 122 ``mach webidl-example HTMLStyleElement``. |
