Bug 928195 - Part 5: Add docs for WebIDL and the build system

DONTBUILD (NPOTB)

--HG--
extra : rebase_source : 24ea7ebca4ae151073502267b5123d2160b28d8e

build/docs/index.rst

@@ -28,6 +28,7 @@ Important Concepts
    mozinfo
    preprocessor
    jar-manifests
+   webidl
 
 mozbuild
 ========

build/docs/webidl.rst

@@ -0,0 +1,137 @@
+.. _webidl:
+
+======
+WebIDL
+======
+
+WebIDL describes interfaces web browsers are supposed to implement.
+
+The interaction between WebIDL and the build system is somewhat complex.
+This document will attempt to explain how it all works.
+
+Overview
+========
+
+``.webidl`` files throughout the tree define interfaces the browser
+implements. Since Gecko/Firefox is implemented in C++, there is a
+mechanism to convert these interfaces and associated metadata to
+C++ code. That's where the build system comes into play.
+
+All the code for interacting with ``.webidl`` files lives under
+``dom/bindings``. There is code in the build system to deal with
+WebIDLs explicitly.
+
+WebIDL source file flavors
+==========================
+
+Not all ``.webidl`` files are created equal! There are several flavors,
+each represented by a separate symbol from :ref:`mozbuild_symbols`.
+
+WEBIDL_FILES
+   Refers to regular/static ``.webidl`` files. Most WebIDL interfaces
+   are defined this way.
+
+GENERATED_EVENTS_WEBIDL_FILES
+   In addition to generating a binding, these ``.webidl`` files also
+   generate an event source file.
+
+PREPROCESSED_WEBIDL_FILES
+   The ``.webidl`` files are generated by preprocessing an input file.
+   They otherwise behave like **WEBIDL_FILES**.
+
+TEST_WEBIDL_FILES
+   Like **WEBIDL_FILES** but the interfaces are for testing only and
+   aren't shipped with the browser.
+
+PREPROCESSED_TEST_WEBIDL_FILES
+   Like **TEST_WEBIDL_FILES** except the ``.webidl`` is obtained via
+   preprocessing, much like **PREPROCESSED_WEBIDL_FILES**.
+
+GENERATED_WEBIDL_FILES
+   The ``.webidl`` for these is obtained through an *external*
+   mechanism. Typically there are custom build rules for producing these
+   files.
+
+Producing C++ code
+==================
+
+The most complicated part about WebIDLs is the process by which
+``.webidl`` files are converted into C++.
+
+The process begins by staging every ``.webidl`` file to a common
+location. For static files, this involves symlinking. However,
+preprocessed and externally-generated ``.webidl`` have special actions.
+
+Producing C++ code from ``.webidl`` consists of 3 logical steps:
+parsing, global generation, and bindings generation.
+
+Parsing
+-------
+
+*Every* ``.webidl`` is fed into a single parser instance. When a single
+``.webidl`` file changes, *every* ``.webidl`` needs to be reparsed.
+
+Global Generation
+-----------------
+
+Global generation takes the parser output and produces some
+well-defined output files. These output files essentially depend on
+every input ``.webidl``.
+
+Binding Generation
+------------------
+
+Binding generation refers to the process of generating output files
+corresponding to a particular ``.webidl`` file. For all ``.webidl`` files,
+we generate a ``*Binding.h`` and ``*Binding.cpp`` file. For generated
+events ``.webidl`` files, we also generate ``*.h`` and ``*.cpp`` files.
+
+Requirements
+============
+
+This section aims to document the build and developer workflow requirements
+for WebIDL.
+
+Parser unit tests
+   There are parser tests provided by ``dom/bindings/parser/runtests.py``
+   that should run as part of ``make check``. There must be a mechanism
+   to run the tests in *human* mode so they output friendly error
+   messages.
+
+Mochitests
+   There are various mochitests under ``dom/bindings/test``. They should
+   be runnable through the standard mechanisms.
+
+Test interfaces are generated as part of the build
+   ``TestExampleGenBinding.cpp`` calls into methods from the
+   ``TestExampleInterface`` and ``TestExampleProxyInterface`` interfaces.
+   These interfaces need to be generated as part of the build.
+
+Running tests automatically rebuilds
+   When a developer runs the WebIDL tests, she expects any necessary rebuilds
+   to occur.
+
+   This is faciliated through ``mach webidl-test``.
+
+Minimal rebuilds
+   Reprocessing every output for every change is expensive. So we don't
+   inconvenience people changing ``.webidl`` files, the build system
+   should only perform a minimal rebuild when sources change.
+
+Explicit method for performing codegen
+   There needs to be an explicit method for incurring code generation.
+   It needs to cover regular and test files.
+
+   This is implemented via ``make export`` in ``dom/bindings``.
+
+No-op binding generation should be fast
+   So developers touching ``.webidl`` files are not inconvenienced,
+   no-op binding generation should be fast. Watch out for the build system
+   processing large dependency files it doesn't need in order to perform
+   code generation.
+
+Ability to generate example files
+   *Any* interface can have example ``.h``/``.cpp`` files generated.
+   There must be a mechanism to facilitate this.
+
+   This is currently facilitated through ``mach webidl-example``.