index.rst (4444B)
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``, ``TestExampleProxyInterface``, 87 ``TestExampleThrowingConstructorInterface``, 88 and ``TestExampleWorkerInterface`` interfaces. 89 These interfaces need to be generated as part of the build. These 90 interfaces should not be exported or packaged. 91 92 There is a ``compiletests`` make target in ``dom/bindings`` that 93 isn't part of the build that facilitates turnkey code generation 94 and test file compilation. 95 96 Minimal rebuilds 97 Reprocessing every output for every change is expensive. So we don't 98 inconvenience people changing ``.webidl`` files, the build system 99 should only perform a minimal rebuild when sources change. 100 101 This logic is mostly all handled in 102 :py:class:`mozwebidlcodegen.WebIDLCodegenManager`. The unit tests for 103 that Python code should adequately test typical rebuild scenarios. 104 105 Bug 940469 tracks making the existing implementation better. 106 107 Explicit method for performing codegen 108 There needs to be an explicit method for invoking code generation. 109 It needs to cover regular and test files. 110 111 This is implemented via ``make export`` in ``dom/bindings``. 112 113 No-op binding generation should be fast 114 So developers touching ``.webidl`` files are not inconvenienced, 115 no-op binding generation should be fast. Watch out for the build system 116 processing large dependency files it doesn't need in order to perform 117 code generation. 118 119 Ability to generate example files 120 *Any* interface can have example ``.h``/``.cpp`` files generated. 121 There must be a mechanism to facilitate this. 122 123 This is currently facilitated through ``mach webidl-example``. e.g. 124 ``mach webidl-example HTMLStyleElement``.