michael@0: .. _webidl:
michael@0: 
michael@0: ======
michael@0: WebIDL
michael@0: ======
michael@0: 
michael@0: WebIDL describes interfaces web browsers are supposed to implement.
michael@0: 
michael@0: The interaction between WebIDL and the build system is somewhat complex.
michael@0: This document will attempt to explain how it all works.
michael@0: 
michael@0: Overview
michael@0: ========
michael@0: 
michael@0: ``.webidl`` files throughout the tree define interfaces the browser
michael@0: implements. Since Gecko/Firefox is implemented in C++, there is a
michael@0: mechanism to convert these interfaces and associated metadata to
michael@0: C++ code. That's where the build system comes into play.
michael@0: 
michael@0: All the code for interacting with ``.webidl`` files lives under
michael@0: ``dom/bindings``. There is code in the build system to deal with
michael@0: WebIDLs explicitly.
michael@0: 
michael@0: WebIDL source file flavors
michael@0: ==========================
michael@0: 
michael@0: Not all ``.webidl`` files are created equal! There are several flavors,
michael@0: each represented by a separate symbol from :ref:`mozbuild_symbols`.
michael@0: 
michael@0: WEBIDL_FILES
michael@0:    Refers to regular/static ``.webidl`` files. Most WebIDL interfaces
michael@0:    are defined this way.
michael@0: 
michael@0: GENERATED_EVENTS_WEBIDL_FILES
michael@0:    In addition to generating a binding, these ``.webidl`` files also
michael@0:    generate a source file implementing the event object in C++
michael@0: 
michael@0: PREPROCESSED_WEBIDL_FILES
michael@0:    The ``.webidl`` files are generated by preprocessing an input file.
michael@0:    They otherwise behave like *WEBIDL_FILES*.
michael@0: 
michael@0: TEST_WEBIDL_FILES
michael@0:    Like *WEBIDL_FILES* but the interfaces are for testing only and
michael@0:    aren't shipped with the browser.
michael@0: 
michael@0: PREPROCESSED_TEST_WEBIDL_FILES
michael@0:    Like *TEST_WEBIDL_FILES* except the ``.webidl`` is obtained via
michael@0:    preprocessing, much like *PREPROCESSED_WEBIDL_FILES*.
michael@0: 
michael@0: GENERATED_WEBIDL_FILES
michael@0:    The ``.webidl`` for these is obtained through an *external*
michael@0:    mechanism. Typically there are custom build rules for producing these
michael@0:    files.
michael@0: 
michael@0: Producing C++ code
michael@0: ==================
michael@0: 
michael@0: The most complicated part about WebIDLs is the process by which
michael@0: ``.webidl`` files are converted into C++.
michael@0: 
michael@0: This process is handled by code in the :py:mod:`mozwebidlcodegen`
michael@0: package. :py:class:`mozwebidlcodegen.WebIDLCodegenManager` is
michael@0: specifically where you want to look for how code generation is
michael@0: performed. This includes complex dependency management.
michael@0: 
michael@0: Requirements
michael@0: ============
michael@0: 
michael@0: This section aims to document the build and developer workflow requirements
michael@0: for WebIDL.
michael@0: 
michael@0: Parser unit tests
michael@0:    There are parser tests provided by ``dom/bindings/parser/runtests.py``
michael@0:    that should run as part of ``make check``. There must be a mechanism
michael@0:    to run the tests in *human* mode so they output friendly error
michael@0:    messages.
michael@0: 
michael@0:    The current mechanism for this is ``mach webidl-parser-test``.
michael@0: 
michael@0: Mochitests
michael@0:    There are various mochitests under ``dom/bindings/test``. They should
michael@0:    be runnable through the standard mechanisms.
michael@0: 
michael@0: Working with test interfaces
michael@0:    ``TestExampleGenBinding.cpp`` calls into methods from the
michael@0:    ``TestExampleInterface`` and ``TestExampleProxyInterface`` interfaces.
michael@0:    These interfaces need to be generated as part of the build. These
michael@0:    interfaces should not be exported or packaged.
michael@0: 
michael@0:    There is a ``compiletests`` make target in ``dom/bindings`` that
michael@0:    isn't part of the build that facilitates turnkey code generation
michael@0:    and test file compilation.
michael@0: 
michael@0: Minimal rebuilds
michael@0:    Reprocessing every output for every change is expensive. So we don't
michael@0:    inconvenience people changing ``.webidl`` files, the build system
michael@0:    should only perform a minimal rebuild when sources change.
michael@0: 
michael@0:    This logic is mostly all handled in
michael@0:    :py:class:`mozwebidlcodegen.WebIDLCodegenManager`. The unit tests for
michael@0:    that Python code should adequately test typical rebuild scenarios.
michael@0: 
michael@0:    Bug 940469 tracks making the existing implementation better.
michael@0: 
michael@0: Explicit method for performing codegen
michael@0:    There needs to be an explicit method for invoking code generation.
michael@0:    It needs to cover regular and test files.
michael@0: 
michael@0:    This is implemented via ``make export`` in ``dom/bindings``.
michael@0: 
michael@0: No-op binding generation should be fast
michael@0:    So developers touching ``.webidl`` files are not inconvenienced,
michael@0:    no-op binding generation should be fast. Watch out for the build system
michael@0:    processing large dependency files it doesn't need in order to perform
michael@0:    code generation.
michael@0: 
michael@0: Ability to generate example files
michael@0:    *Any* interface can have example ``.h``/``.cpp`` files generated.
michael@0:    There must be a mechanism to facilitate this.
michael@0: 
michael@0:    This is currently facilitated through ``mach webidl-example``. e.g.
michael@0:    ``mach webidl-example HTMLStyleElement``.