For Blink developers, the main details of IDLs are the extended attributes, which control implementation-specific behavior.

See Blink IDL Extended Attributes for extensive details.

Our goal is to converge Blink's IDL and Web IDL. The grammar is almost identical; see below.

Basics of IDL

Here is an example of IDL files:

[CustomToV8]
interface Node {
  const unsigned short ELEMENT_NODE = 1;
  attribute Node parentNode;
  [TreatReturnedNullStringAs=Null] attribute DOMString nodeName;
  [Custom] Node appendChild(Node newChild);
  void addEventListener(DOMString type, EventListener listener, optional boolean useCapture);
};

• An 'operation' (Web IDL) is more commonly called a 'method'.
• An 'argument' (Web IDL) is more formally a 'parameter'.

The key points are as follows:

• An IDL file controls how the bindings code between JavaScript engine and the Blink implementation is generated.
• Extended attributes enable you to control the bindings code more in detail.
• There are ~80 extended attributes, explained in a separate page.
• Extended attributes can be specified on interfaces, methods, attributes and parameters (but not constants, enums, etc.).

A simple IDL file template looks like:

interface INTERFACE_NAME {
    const unsigned long value = 12345;
    attribute Node node;
    void func(int param, ...);
};

[
    EXTATTR,
    EXTATTR,
    ...
]
interface INTERFACE_NAME {
   const unsigned long value = 12345;
   [EXTATTR, EXTATTR, ...] attribute Node node;
   [EXTATTR, EXTATTR, ...] void func([EXTATTR, EXTATTR, ...] int param, ...);
};

Syntax

IDL extended attribute validator

Previously there had been many bugs caused by typos in extended attributes in IDL files. To avoid such bugs, the extended attribute validator was introduced to the Blink build flow to check if all the extended attributes used in IDL files are implemented in the code generator. If you use an extended attribute not implemented in code generators, the extended attribute validator fails, and the Blink build fails.

A list of IDL attributes implemented in code generators is described in IDLExtendedAttributes.txt. If you want to add a new IDL attribute, you need to

1. add the extended attribute to Source/bindings/IDLExtendedAttributes.txt.
2. add the explanation to the extended attributes document.
3. add test cases to run-bindings-tests (explained below).

run-bindings-tests

Tools/Scripts/run-bindings-tests tests the code generator, including its treatment of extended attributes. Specifically, run-bindings-tests compiles the IDL files in Source/bindings/tests/idls, and then compares the results against reference files in Source/bindings/tests/results. For example, run-bindings-tests reads Source/bindings/tests/idls/TestObj.idl, and then compares the generated results against Source/bindings/tests/results/V8TestObj.h and Source/bindings/tests/results/V8TestObj.cpp, reporting any differences.

If you change the behavior of code generators or add a new extended attribute, please add test cases to Source/bindings/tests/idls. You can reset the run-bindings-tests results using the --reset-results option:

Tools/Scripts/run-bindings-tests --reset-results

The objective of run-bindings-tests is to show you and reviewers how the code generation is changed by your patch. If you change the behavior of code generators, you need to update the results of run-bindings-tests. (This is checked by a presubmit script, but not checked by trybot tests.) If the results are out of date prior to your CL, please rebaseline them separately, before committing your CL, as otherwise it will be difficult to distinguish which changes are due to your CL and which are due to rebaselining due to older CLs.

Where is the bindings code generated?

By reading this document you can learn how extended attributes work. However, the best practice to understand extended attributes is to try to use some and watch what kind of bindings code is generated.

If you change an IDL file and rebuild (e.g., with ninja or Make), the bindings for that IDL file (and possibly others, if there are dependents) will be rebuilt. If the bindings have changed (in ninja), or even if they haven't (in other build systems), it will also recompile the bindings code. Regenerating bindings for a single IDL file is very fast, but regenerating all of them takes several minutes of CPU time.

In case of XXX.idl in the Release build, the bindings code is generated in the following files ("Release" becomes "Debug" in the Debug build).

Many parts of the Web IDL spec are not implemented; features are implemented on an as-needed basis.

Dictionaries (hashes, maps) are a commonly used complex data type.

---