mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-05 08:35:26 +00:00
123 lines
4.3 KiB
ReStructuredText
123 lines
4.3 KiB
ReStructuredText
.. _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 a source file implementing the event object in C++
|
|
|
|
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++.
|
|
|
|
This process is handled by code in the :py:mod:`mozwebidlcodegen`
|
|
package. :py:class:`mozwebidlcodegen.WebIDLCodegenManager` is
|
|
specifically where you want to look for how code generation is
|
|
performed. This includes complex dependency management.
|
|
|
|
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.
|
|
|
|
The current mechanism for this is ``mach webidl-parser-test``.
|
|
|
|
Mochitests
|
|
There are various mochitests under ``dom/bindings/test``. They should
|
|
be runnable through the standard mechanisms.
|
|
|
|
Working with test interfaces
|
|
``TestExampleGenBinding.cpp`` calls into methods from the
|
|
``TestExampleInterface`` and ``TestExampleProxyInterface`` interfaces.
|
|
These interfaces need to be generated as part of the build. These
|
|
interfaces should not be exported or packaged.
|
|
|
|
There is a ``compiletests`` make target in ``dom/bindings`` that
|
|
isn't part of the build that facilitates turnkey code generation
|
|
and test file compilation.
|
|
|
|
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.
|
|
|
|
This logic is mostly all handled in
|
|
:py:class:`mozwebidlcodegen.WebIDLCodegenManager`. The unit tests for
|
|
that Python code should adequately test typical rebuild scenarios.
|
|
|
|
Bug 940469 tracks making the existing implementation better.
|
|
|
|
Explicit method for performing codegen
|
|
There needs to be an explicit method for invoking 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``. e.g.
|
|
``mach webidl-example HTMLStyleElement``.
|