dom/bindings/docs/index.rst

   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``.