diff options
Diffstat (limited to 'chromium/docs/website/site/blink/webidl/index.md')
| -rw-r--r-- | chromium/docs/website/site/blink/webidl/index.md | 682 |
1 files changed, 0 insertions, 682 deletions
diff --git a/chromium/docs/website/site/blink/webidl/index.md b/chromium/docs/website/site/blink/webidl/index.md deleted file mode 100644 index 3165d6f2d15..00000000000 --- a/chromium/docs/website/site/blink/webidl/index.md +++ /dev/null @@ -1,682 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: webidl -title: Web IDL in Blink ---- - -*Blink developers (non-bindings development): for general IDL use, see [Web IDL -interfaces](/developers/web-idl-interfaces); for configuring bindings, see -[Blink IDL Extended Attributes](/blink/webidl/blink-idl-extended-attributes); -for IDL dictionaries use, see [IDL dictionaries in -Blink](https://docs.google.com/document/d/1mRB5zbfHd0lX2Y_Hr7g6grzP_L4Xc6_gBRjL-AE7sY8/edit?usp=sharing).* - -[TOC] - -## Overview - -[Web IDL](https://heycam.github.io/webidl/) is a language that defines how -Blink interfaces are bound to V8. You need to write IDL files (e.g. -xml_http_request.idl, element.idl, etc) to expose Blink interfaces to those -external languages. When Blink is built, the IDL files are parsed, and the code -to bind Blink implementations to V8 interfaces automatically generated. - -This document describes practical information about how the IDL bindings work -and how you can write IDL files in Blink. The syntax of IDL files is fairly well -documented in the [Web IDL spec](https://heycam.github.io/webidl/), but it is -too formal to read :-) and there are several differences between the Web IDL -spec and the Blink IDL due to implementation issues. For design docs on bindings -generation, see [IDL build](/developers/design-documents/idl-build) and [IDL -compiler](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLCompiler.md). - -For Blink developers, the main details of IDLs are the extended attributes, -which control implementation-specific behavior: see [Blink IDL Extended -Attributes](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md) -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: - -```none -[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); -}; -``` - -Let us introduce some terms: - -* The above IDL file describes the `Node` **interface**. -* `ELEMENT_NODE` is a **constant** of the `Node` interface. -* `parentNode` and `nodeName` are **attributes** of the `Node` - interface. -* `appendChild(...)` and `addEventListener(...)` are **operations** of - the `Node` interface. -* `type`, `listener` and `useCapture` are **arguments** of the - `addEventListener` operation. -* `[CustomToV8]`, `[TreatReturnedNullStringAs=Null]` and `[Custom]` - are **extended attributes**. - -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 ~60 extended attributes, explained in [a separate - page](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md). -* Extended attributes can be specified on interfaces, methods, - attributes, arguments, and types (but not constants, enums, etc.). - -The valid extended attributes depend on where they attach: interfaces and -methods have different extended attributes. - -A simple IDL file template looks like: - -```none -interface INTERFACE_NAME { - const unsigned long value = 12345; - attribute Node node; - void func(long argument, ...); -}; -``` - -With extended attributes, this looks like: - -```none -[ - EXTATTR, - EXTATTR, - ..., -] interface INTERFACE_NAME { - const unsigned long value = 12345; - [EXTATTR, EXTATTR, ...] attribute Node node; - [EXTATTR, EXTATTR, ...] void func([EXTATTR, EXTATTR, ...] optional [EXTATTR] long argument, ...); -}; -``` - -## Syntax - -Blink IDL is a dialect of Web IDL. The lexical syntax is identical, but the -phrase syntax is slightly different. - -Implementation-wise, the lexer and parser are written in -[PLY](http://www.dabeaz.com/ply/) (Python lex-yacc), an implementation of lex -and yacc for Python. A standard-compliant lexer is used (Chromium -[tools/idl_parser/idl_lexer.py](https://code.google.com/p/chromium/codesearch#chromium/src/tools/idl_parser/idl_lexer.py)). -The parser (Blink -[bindings/scripts/blink_idl_parser.py](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/scripts/blink_idl_parser.py)) -derives from a standard-compliant parser (Chromium -[tools/idl_parser/idl_parser.py](https://code.google.com/p/chromium/codesearch#chromium/src/tools/idl_parser/idl_parser.py)). - -Blink deviations from the Web IDL standard can be seen as the BNF production -rules in the derived parser. - -**Style** - -Style guidelines are to generally follow [Blink style](/blink/coding-style) for -C++, with a few points highlighted, addenda, and exceptions. These are not -enforced by a pre-submit test, but do assist legibility: - -* Include the [current Blink license - header](http://www.chromium.org/blink/coding-style#TOC-License) in - new files -* For IDL based on standards/specifications: - * Include a comment with the URL of the spec (and specific - section, if possible) where the IDL is defined. - * Follow any IDL samples given in specs. - * Keep the order of interface and dictionary members the same as - in the spec. - * Document any deviations from the spec with `// TODO(name or bug - link):` comments -* 4-space indent. -* Avoid line breaks, notably: - * Keeping extended attributes of members (attributes, constants, - and operations) on the same line as the member. - * Generally keep argument lists of methods on the same line as the - definition. Ok to break if it's v. long or for overloaded - methods. - * For overloaded methods, it is ok to use line breaks to group - arguments. E.g., if one method has arguments (a, b, c) and the - other has arguments (a, b, c, d, e, f), it is ok to include a - line break between c and d, to clarify the grouping. -* Alphabetize lists of extended attributes. -* For extended attributes on interface, put each on a separate line - with a trailing comma, except for the last one. Note that this is - *not* style used in the standard, which uses a horizontal list on - the line before the interface. Please omit the `[]` list if it's - empty. Examples of Blink style: - -```none -[ - A, - B /* No trailing commas on the last extended attribute */ -] interface Foo { - ... -}; -interface Bar { - ... -}; -``` - -* No spacing for horizontal alignment, except for lists of constants. -* For anonymous special operations, leave a space between the type and - the parenthesize argument list; if you don't, the type looks like a - function name! - -```none -getter DOMString (unsigned long index); // Not: DOMString(unsigned long index) -``` - -* For special operations, the (first) argument to indexed property - operations should be called `index`, and the (first) argument to - named property operations should be called `name`; the second - argument in property setters should be called `value`. For example: - -```none -// Indexed property operations -getter DOMString (unsigned long index); -setter DOMString (unsigned long index, DOMString value); -deleter boolean (unsigned long index); - -// Named property operations -getter DOMString (DOMString name); -setter DOMString (DOMString name, DOMString value); -deleter boolean (DOMString name); -``` - -## Semantics - -Web IDL exposes an interface to JavaScript, which is implemented in C++. Thus -its semantics bridge these two languages, though it is not identical to either. -Web IDL's semantics are much closer to C++ than to JavaScript – in practice, it -is a relatively thin abstraction layer over C++. Thus C++ implementations are -quite close to the IDL spec, though the resulting interface is somewhat -unnatural from a JavaScript perspective: it behaves differently from normal -JavaScript libraries. - -### Types - -*See: [Web IDL types](http://heycam.github.io/webidl/#idl-types).* - -[Primitive types](http://heycam.github.io/webidl/#dfn-primitive-type) in Web IDL -are very close to fundamental types in C++ (booleans, characters, integers, and -floats), though note that there is no `int` type in Web IDL (specs usually use -`long` instead). - -### undefined and null - -JavaScript has two special values, `undefined` and `null`, which are often -confusing and do not fit easily into C++. Indeed, precise behavior of -`undefined` in Web IDL has varied over time and is under discussion (see W3C Bug -[23532](https://www.w3.org/Bugs/Public/show_bug.cgi?id=23532) - Dealing with -undefined). - -Behavior on `undefined` and `null` **MUST** be tested in web tests, as these can -be passed and are easy to get wrong. If these tests are omitted, there may be -crashes (which will be caught by ClusterFuzz) or behavioral bugs (which will -show up as web pages or JavaScript libraries breaking). - -For the purposes of Blink, behavior can be summarized as follows: - -* `undefined` and `null` are valid values for **basic types**, and are - automatically converted. - * Conversion follows [ECMAScript type - mapping](http://heycam.github.io/webidl/#dfn-convert-ecmascript-to-idl-value), - which generally implements JavaScript [Type - Conversion](https://tc39.github.io/ecma262/#sec-type-conversion), - e.g. [ToBoolean](https://tc39.github.io/ecma262/#sec-toboolean), - [ToNumber](https://tc39.github.io/ecma262/#sec-tonumber), - [ToString](https://tc39.github.io/ecma262/#sec-tostring). - * They may be converted to different values, notably `"undefined"` - and `"null"` for `DOMString`. - * For numeric types, this can be affected by the extended - attributes `[Clamp]` and `[EnforceRange]`. - * `[Clamp]` changes the value so that it is valid. - * `[EnforceRange]` throws a `TypeError` on these invalid - values. -* for **interface types**, `undefined` and `null` are both treated as - `null`, which maps to `nullptr`. - * for nullable interface types, like `Node?`, `null` is a valid - value, and thus `nullptr` is passed to the C++ implementation - * for non-nullable interface types, like `Node` (no `?`), `null` - is *not* a valid value, and a `TypeError` is thrown, as in - JavaScript - [ToObject](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-toobject). - * *However,* this nullability check is *not* done by default: - it is only done if `[LegacyInterfaceTypeChecking]` is - specified on the interface or member (see Bug - [249598](https://code.google.com/p/chromium/issues/detail?id=249598): - Throw TypeError when null is specified to non-nullable - interface parameter) - * Thus if `[LegacyInterfaceTypeChecking]` is specified in the - IDL, you do *not* need to have a null check in the Blink - implementation, as the bindings code already does this, but - if `[LegacyInterfaceTypeChecking]` is not specified, you - *do* need to have a null check in the Blink implementation. -* for **dictionary types**, `undefined` and `null` both correspond to - an empty dictionary -* for **union types**, `undefined` and `null` are assigned to a type - that can accept them, if possible: null, empty dictionary, or - conversion to basic type -* **function resolution** - * `undefined` affects function resolution, both as an optional - argument and for overloaded operations, basically being omitted - if trailing (but some exceptions apply). This is complicated - (see W3C Bug - [23532](https://www.w3.org/Bugs/Public/show_bug.cgi?id=23532) - - Dealing with undefined) and not currently implemented. - Further, note that in some cases one wants different behavior for `f()` - and `f(undefined)`, which requires an explicit overload, not an optional - argument; a good example is `Window.alert()`, namely `alert()` vs. - `alert(undefined)` (see W3C Bug - [25686](https://www.w3.org/Bugs/Public/show_bug.cgi?id=25686)). - * `null` affects function resolution for overloaded operations, - due to preferring nullable types, but this is the only effect. - -### Function resolution - -Web IDL has *required* arguments and *optional* arguments. JavaScript does not: -omitted arguments have `undefined` value. In Web IDL, omitting optional -arguments is *not* the same as explicitly passing `undefined`: they call have -different behavior (defined in the spec prose), and internally call different -C++ functions implementing the operation. - -Thus if you have the following Web IDL function declaration: - -```none -interface A { - void foo(long x); - }; -``` - -...the JavaScript `a = new A(); a.foo()` will throw a `TypeError`. This is -specified in Web IDL, and thus done by the binding code. - -However, in JavaScript the corresponding function can be called without -arguments: - -```none -function foo(x) { return x } - foo() // undefined -``` - -Note that `foo()` and `foo(undefined)` are almost identical calls (and for this -function have identical behavior): it only changes the value of -`arguments.length`. - -To get *similar* behavior in Web IDL, the argument can be explicitly specified -as `optional` (or more precisely, `optional` with `undefined` as a default -value). However, these do *not* need to have the same behavior, and do *not* -generate the same code: the spec may define different behavior for these calls, -and the bindings call the implementing C++ functions with a different number of -arguments, which is resolved by C++ overloading, and these may be implemented by -different functions. - -For example, given an optional argument such as: - -```none -interface A { - void foo(optional long x); - }; -``` - -This results in a = new A(); a.foo() being legal, and calling the underlying -Blink C++ function implementing `foo` with no arguments, while -`a.foo(undefined)` calls the underlying Blink function with one argument. - -For *overloaded* operations, the situation is more complicated, and not -currently implemented in Blink (Bug -[293561](https://code.google.com/p/chromium/issues/detail?id=293561)). See the -[overload resolution -algorithm](http://heycam.github.io/webidl/#dfn-overload-resolution-algorithm) in -the spec for details. - -Pragmatically, passing `undefined` for an optional argument is necessary if you -wish to specify a value for a later argument, but not earlier ones, but does not -necessarily mean that you mean to pass in `undefined` explicitly; these instead -get the special value "missing". - -Passing `undefined` to the last optional argument has unclear behavior for the -value of the argument, but does mean that it resolves it to the operation with -the optional argument, rather than others. (It then prioritizes nullable types -and dictionary types, or unions thereof.) For example: - -```none -interface A { - void foo(optional long x); - void foo(Node x); - }; -``` - -This results in a = new A(); a.foo(undefined) resolving to the first `foo`, it -is not clear if the resulting call is `a.foo()`, to `a.foo` with "missing", or -(most likely) `a.foo(undefined)` (here using the first overloaded function): it -affect overload resolution, but perhaps not argument values. Note that -`undefined` is also a legitimate value for the argument of `Node` type, so it -would not be illegal, but the overload resolution algorithm first picks optional -arguments in this case. - -Note that Blink code implementing a function can also check arguments, and -similarly, JavaScript functions can check arguments, and access the number of -arguments via `arguments.length`, but these are not specified by the *language* -or checked by bindings. - -***Warning:*** `undefined` is a *valid value* for required arguments, and many -interfaces *depend* on this behavior particularly booleans, numbers, and -dictionaries. Explicitly passing `undefined`, as in `a.foo(undefined)`, does -*not* cause a type error (assuming `foo` is unary). It is clearer if the -parameter is marked as `optional` (this changes semantics: the argument can now -also be omitted, not just passed explicitly as `undefined`), but this is not -always done in the spec or in Blink's IDL files. - -## File organization - -The Web IDL spec treats the Web API as a single API, spread across various IDL -fragments. In practice these fragments are `.idl` files, stored in the codebase -alongside their implementation, with basename equal to the interface name. Thus -for example the fragment defining the `Node` interface is written in n`ode.idl`, -which is stored in the `third_party/blink/renderer/core/dom` directory, and is -accompanied by `node.h` and `node.cc` in the same directory. In some cases the -implementation has a different name, in which case there must be an -`[ImplementedAs=...]` extended attribute in the IDL file, and the `.h/.cc` files -have basename equal to the value of the `[ImplementedAs=...]`. - -For simplicity, each IDL file contains a *single* interface or dictionary, and -contains all information needed for that definition, except for dependencies -(below), notably any enumerations, implements statements, typedefs, and callback -functions. - -### Dependencies - -In principle (as a matter of the Web IDL spec) any IDL file can depend on any -other IDL file, and thus changing one file can require rebuilding all the -dependents. In practice there are 4 kinds of dependencies (since other required -definitions, like enumerations and typedefs, are contained in the IDL file for -the interface): - -* `partial interface` – a single interface can be spread across a - single main `interface` statement (in one file) and multiple other - `partial interface` statements, each in a separate file (each - `partial interface` statement is associated with a single main - `interface` statement). In this case the IDL file containing the - partial interface has some other name, often the actual interface - name plus some suffix, and is generally named after the implementing - class for the members it contains. From the point of view of spec - authors and compilation, the members are just treated as if they - appeared in the main definition. From the point of view of the - build, these are awkward to implement, since these are incoming - dependencies, and cannot be determined from looking at the main - interface IDL file itself, thus requiring a global dependency - resolution step. -* `implements` – this is essentially multiple inheritance: an - interface can implement multiple other interfaces, and a given - interface can be implemented by multiple other interfaces. This is - specified by implements statements in the implementing file (these - are outgoing dependencies), though from the perspective of the build - the interface → .idl filename of that interface data is required, - and is global information (because the .idl files are spread across - the source tree). -* **Ancestors** – an interface may have a parent, which in turn may - have a parent. The immediate parent can be determined from looking - at a single IDL file, but the more distant ancestors require - dependency resolution (computing an ancestor chain). -* **Used interfaces (cross dependencies)** – a given interface may - *use* other interfaces as *types* in its definitions; the contents - of the used interfaces *may* affect the bindings generated for the - using interface, though this is often a *shallow dependency* (see - below). - -In practice, what happens is that, when compiling a given interfaces, its -partial interfaces and the other interfaces it implements are merged into a -single data structure, and that is compiled. There is a small amount of data -recording where exactly a member came from (so the correct C++ class can be -called), and a few other extended attributes for switching the -partial/implemented interface on or off, but otherwise it is as if all members -were specified in a single `interface` statement. This is a **deep dependency** -relationship: *any* change in the partial/implemented interface changes the -bindings for the overall (merged) interface, since *all* the data is in fact -used. - -Bindings for interfaces in general do *not* depend on their ancestors, beyond -the name of their immediate parent. This is because the bindings just generate a -class, which refers to the parent class, but otherwise is subject to information -hiding. However, in a few cases bindings depend on whether the interface -inherits from some other interface (notably EventHandler or Node), and in a few -cases bindings depend on the extended attributes of ancestors (these extended -attributes are "inherited"; the list is -[compute_dependencies.INHERITED_EXTENDED_ATTRIBUTES](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/scripts/compute_interfaces_info_overall.py?q=INHERITED_EXTENDED_ATTRIBUTES&l=59), -and consists of extended attributes that affect memory management). There is -thus a **shallow dependency** on ancestors, specifically only on the ancestor -chain and on inherited extended attributes, not on the other contents of -ancestors. - -On the other hand, the dependencies on used interfaces – so-called **cross -dependencies** – are generally **shallow dependency** relationships: the using -interface does not need to know much about the used interface (currently just -the name of the implementing class, and whether the interface is a callback -interface or not). Thus *almost all changes* in the used interface do not change -the bindings for the using interface: the public information used by other -bindings is minimal. There is one exception, namely the `[PutForwards]` extended -attribute (in standard Web IDL), where the using interface needs to know the -type of an attribute in the used interface. This "generally shallow" -relationship may change in future, however, as being able to inspect the used -interface can simplify the code generator. This would require the using -interface to depend on used interfaces, either rebuilding all using interfaces -whenever a used interface is changed, or clearly specifying or computing the -public information (used by code generator of other interfaces) and depending -only on that. - -## IDL extended attribute validator - -To avoid bugs caused by typos in extended attributes in IDL files, 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](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/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). - -Note that the validator checks for known extended attributes and their arguments -(if any), but does not enforce correct use of the the attributes. A warning will -not be issued if, for example, `[Clamp]` is specified on an interface. - -## Tests - -### Reference tests (run-bindings-tests) - -[third_party/blink/tools/run_bindings_tests.py](https://cs.chromium.org/chromium/src/third_party/blink/tools/run_bindings_tests.py) -tests the code generator, including its treatment of extended attributes. -Specifically, run_bindings_tests.py compiles the IDL files in -[bindings/tests/idls](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/tests/idls/), -and then compares the results against reference files in -[bindings/tests/results](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/tests/results/). -For example, run_bindings_tests.py reads test_object.idl, and then compares the -generated results against v8_test_object.h and v8_test_object.cc, reporting any -differences. - -If you change the behavior of the code generator or add a new extended -attribute, please add suitable test cases, preferably *reusing* existing IDL -files (this is to minimize size of diffs when making changes to overall -generated bindings). You can reset the run-bindings-tests results using the ---reset-results option: - -```none -third_party/blink/tools/run_bindings_tests.py --reset-results -``` - -run_bindings_tests.py is run in a presubmit script for any changes to -Source/bindings: this requires you to update test results when you change the -behavior of the code generator, and thus if test results get out of date, the -presubmit test will fail: you won't be able to upload your patch via git-cl, and -the CQ will refuse to process the patch. - -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.** - -Despite these checks, sometimes the test results can get out of date; this is -primarily due to dcommitting or changes in real IDL files (not in -Source/bindings) that are used in test cases. 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. - -Note that using real interfaces in test IDL files means changes to real IDL -files can break run-bindings-tests (e.g., Blink -[r174804](https://src.chromium.org/viewvc/blink?revision=174804&view=revision)/CL -[292503006](https://codereview.chromium.org/292503006/): Oilpan: add -\[WillBeGarbageCollected\] for Node., since Node is inherited by test files). -This is ok (we're not going to run run_bindings_tests.py on every IDL edit, and -it's easy to fix), but something to be aware of. - -It is also possible for run_bindings_tests.py to break for other reasons, since -it use the developer's local tree: it thus may pass locally but fail remotely, -or conversely. For example, renaming Python files can result in outdated -bytecode (.pyc files) being used locally and succeeding, even if -run_bindings_tests.py is incompatible with current Python source (.py), as -discussed and fixed in CL -[301743008](https://codereview.chromium.org/301743008/). - -### Behavior tests - -To test behavior, use [web -tests](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_tests.md), -most simply actual interfaces that use the behavior you're implementing. If -adding new behavior, it's preferable to make code generator changes and the -first actual use case in the same CL, so that it is properly tested, and the -changes appear in the context of an actual change. If this makes the CL too -large, these can be split into a CG-only CL and an actual use CL, committed in -sequence, but unused features should not be added to the CG. - -For general behavior, like type conversions, there are some internal tests, like -[bindings/webidl-type-mapping.html](https://cs.chromium.org/chromium/src/third_party/WebKit/LayoutTests/bindings/webidl-type-mapping.html), -which uses -[testing/type_conversions.idl](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/testing/type_conversions.idl). -There are also some other IDL files in -[testing](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/testing/), -like -[testing/internals.idl](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/testing/internals.idl). - -## 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). - -```none -out/Release/gen/third_party/blink/renderer/bindings/{core,modules}/v8_xxx.{h,cc} -``` - -## Limitations and improvements - -A few parts of the Web IDL spec are not implemented; features are implemented on -an as-needed basis. See -[component:Blink>Bindings](https://bugs.chromium.org/p/chromium/issues/list?q=component:Blink%3EBindings) -for open bugs; please feel free to file bugs or contact bindings developers -([members of -blink-reviews-bindings](https://groups.google.com/a/chromium.org/forum/#!members/blink-reviews-bindings), -or -[bindings/OWNERS](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/OWNERS)) -if you have any questions, problems, or requests. - -Bindings generation can be controlled in many ways, generally by adding an -extended attribute to specify the behavior, sometimes by special-casing a -specific type, interface, or member. If the existing [extended -attributes](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md) -are not sufficient (or buggy), please file a bug and contact bindings -developers! - -Some commonly encountered limitations and suitable workarounds are listed below. -Generally limitations can be worked around by using custom bindings, but these -should be avoided if possible. If you need to work around a limitation, please -put a `TODO` with the bug number (as demonstrated below) in the IDL so that we -can remove the hack when the feature is implemented. - -### Syntax error causes infinite loop - -Some syntax errors cause the IDL parser to enter an infinite loop (Bug -[363830](https://code.google.com/p/chromium/issues/detail?id=363830)). Until -this is fixed, if the compiler hangs, please terminate the compiler and check -your syntax. - -### Type checking - -The bindings do not do full type checking (Bug -[321518](https://code.google.com/p/chromium/issues/detail?id=321518)). They do -some type checking, but not all. Notably nullability is not strictly enforced. -See `[TypeChecking]` under **undefined and null** above to see how to turn on -more standard type checking behavior for interfaces and members. - -## Bindings development - -### Mailing List - -## If working on bindings, you likely wish to join the [blink-reviews-bindings](https://groups.google.com/a/chromium.org/forum/#!forum/blink-reviews-bindings) mailing list. - -### See also - -* [Web IDL interfaces](/developers/web-idl-interfaces) – overview - how-to for Blink developers -* [Blink IDL Extended - Attributes](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md) - – reference for Blink developers and bindings developers -* [IDL build](/developers/design-documents/idl-build) – design doc -* [IDL compiler](/developers/design-documents/idl-compiler) – design - doc - ---- - -Derived from: <http://trac.webkit.org/wiki/WebKitIDL> *Licensed under -[BSD](http://www.webkit.org/coding/bsd-license.html):* - -BSD License - -Copyright (C) 2009 Apple Inc. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, -this list of conditions and the following disclaimer in the documentation and/or -other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY -EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file |