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.
.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
WebIDL source file flavors¶
.webidl files are created equal! There are several flavors,
each represented by a separate symbol from mozbuild Sandbox Symbols.
- Refers to regular/static
.webidlfiles. Most WebIDL interfaces are defined this way.
- In addition to generating a binding, these
.webidlfiles also generate a source file implementing the event object in C++
.webidlfiles are generated by preprocessing an input file. They otherwise behave like WEBIDL_FILES.
- Like WEBIDL_FILES but the interfaces are for testing only and aren’t shipped with the browser.
- Like TEST_WEBIDL_FILES except the
.webidlis obtained via preprocessing, much like PREPROCESSED_WEBIDL_FILES.
.webidlfor 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
specifically where you want to look for how code generation is
performed. This includes complex dependency management.
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.pythat 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
- There are various mochitests under
dom/bindings/test. They should be runnable through the standard mechanisms.
- Working with test interfaces
TestExampleGenBinding.cppcalls into methods from the
TestExampleWorkerInterfaceinterfaces. These interfaces need to be generated as part of the build. These interfaces should not be exported or packaged.
There is a
compiletestsmake target in
dom/bindingsthat 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
.webidlfiles, the build system should only perform a minimal rebuild when sources change.
This logic is mostly all handled in
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
- No-op binding generation should be fast
- So developers touching
.webidlfiles 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
.cppfiles generated. There must be a mechanism to facilitate this.
This is currently facilitated through
mach webidl-example. e.g.
mach webidl-example HTMLStyleElement.