1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/bindings/docs/index.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,122 @@
1.4 +.. _webidl:
1.5 +
1.6 +======
1.7 +WebIDL
1.8 +======
1.9 +
1.10 +WebIDL describes interfaces web browsers are supposed to implement.
1.11 +
1.12 +The interaction between WebIDL and the build system is somewhat complex.
1.13 +This document will attempt to explain how it all works.
1.14 +
1.15 +Overview
1.16 +========
1.17 +
1.18 +``.webidl`` files throughout the tree define interfaces the browser
1.19 +implements. Since Gecko/Firefox is implemented in C++, there is a
1.20 +mechanism to convert these interfaces and associated metadata to
1.21 +C++ code. That's where the build system comes into play.
1.22 +
1.23 +All the code for interacting with ``.webidl`` files lives under
1.24 +``dom/bindings``. There is code in the build system to deal with
1.25 +WebIDLs explicitly.
1.26 +
1.27 +WebIDL source file flavors
1.28 +==========================
1.29 +
1.30 +Not all ``.webidl`` files are created equal! There are several flavors,
1.31 +each represented by a separate symbol from :ref:`mozbuild_symbols`.
1.32 +
1.33 +WEBIDL_FILES
1.34 + Refers to regular/static ``.webidl`` files. Most WebIDL interfaces
1.35 + are defined this way.
1.36 +
1.37 +GENERATED_EVENTS_WEBIDL_FILES
1.38 + In addition to generating a binding, these ``.webidl`` files also
1.39 + generate a source file implementing the event object in C++
1.40 +
1.41 +PREPROCESSED_WEBIDL_FILES
1.42 + The ``.webidl`` files are generated by preprocessing an input file.
1.43 + They otherwise behave like *WEBIDL_FILES*.
1.44 +
1.45 +TEST_WEBIDL_FILES
1.46 + Like *WEBIDL_FILES* but the interfaces are for testing only and
1.47 + aren't shipped with the browser.
1.48 +
1.49 +PREPROCESSED_TEST_WEBIDL_FILES
1.50 + Like *TEST_WEBIDL_FILES* except the ``.webidl`` is obtained via
1.51 + preprocessing, much like *PREPROCESSED_WEBIDL_FILES*.
1.52 +
1.53 +GENERATED_WEBIDL_FILES
1.54 + The ``.webidl`` for these is obtained through an *external*
1.55 + mechanism. Typically there are custom build rules for producing these
1.56 + files.
1.57 +
1.58 +Producing C++ code
1.59 +==================
1.60 +
1.61 +The most complicated part about WebIDLs is the process by which
1.62 +``.webidl`` files are converted into C++.
1.63 +
1.64 +This process is handled by code in the :py:mod:`mozwebidlcodegen`
1.65 +package. :py:class:`mozwebidlcodegen.WebIDLCodegenManager` is
1.66 +specifically where you want to look for how code generation is
1.67 +performed. This includes complex dependency management.
1.68 +
1.69 +Requirements
1.70 +============
1.71 +
1.72 +This section aims to document the build and developer workflow requirements
1.73 +for WebIDL.
1.74 +
1.75 +Parser unit tests
1.76 + There are parser tests provided by ``dom/bindings/parser/runtests.py``
1.77 + that should run as part of ``make check``. There must be a mechanism
1.78 + to run the tests in *human* mode so they output friendly error
1.79 + messages.
1.80 +
1.81 + The current mechanism for this is ``mach webidl-parser-test``.
1.82 +
1.83 +Mochitests
1.84 + There are various mochitests under ``dom/bindings/test``. They should
1.85 + be runnable through the standard mechanisms.
1.86 +
1.87 +Working with test interfaces
1.88 + ``TestExampleGenBinding.cpp`` calls into methods from the
1.89 + ``TestExampleInterface`` and ``TestExampleProxyInterface`` interfaces.
1.90 + These interfaces need to be generated as part of the build. These
1.91 + interfaces should not be exported or packaged.
1.92 +
1.93 + There is a ``compiletests`` make target in ``dom/bindings`` that
1.94 + isn't part of the build that facilitates turnkey code generation
1.95 + and test file compilation.
1.96 +
1.97 +Minimal rebuilds
1.98 + Reprocessing every output for every change is expensive. So we don't
1.99 + inconvenience people changing ``.webidl`` files, the build system
1.100 + should only perform a minimal rebuild when sources change.
1.101 +
1.102 + This logic is mostly all handled in
1.103 + :py:class:`mozwebidlcodegen.WebIDLCodegenManager`. The unit tests for
1.104 + that Python code should adequately test typical rebuild scenarios.
1.105 +
1.106 + Bug 940469 tracks making the existing implementation better.
1.107 +
1.108 +Explicit method for performing codegen
1.109 + There needs to be an explicit method for invoking code generation.
1.110 + It needs to cover regular and test files.
1.111 +
1.112 + This is implemented via ``make export`` in ``dom/bindings``.
1.113 +
1.114 +No-op binding generation should be fast
1.115 + So developers touching ``.webidl`` files are not inconvenienced,
1.116 + no-op binding generation should be fast. Watch out for the build system
1.117 + processing large dependency files it doesn't need in order to perform
1.118 + code generation.
1.119 +
1.120 +Ability to generate example files
1.121 + *Any* interface can have example ``.h``/``.cpp`` files generated.
1.122 + There must be a mechanism to facilitate this.
1.123 +
1.124 + This is currently facilitated through ``mach webidl-example``. e.g.
1.125 + ``mach webidl-example HTMLStyleElement``.
