在做Chromium浏覽器定制化需求時常常需要擴充JS對象以增加js的功能. 在javascript這門程式設計語言的概念裡,一切皆為對象,變量,函數等等一切皆為對象,沒有類的概念,javascript是一門動态語言,它的主要特點是對象的類型和内容是在運作時決定的,是可以不斷變化的. 在javascript的世界裡,根對象是global對象,所有的一切對象皆為global的子孫對象.在浏覽器中,這個global對象的表現為window對象. 在webkit中已實作的對象稱為javascript内部對象,内部對象又分為本地對象(由使用者在js代碼中使用new方法初化始對象之後才能使用)和内置對象(直接在blink初始化好的，如window對象的alert，confirm等）.

一: 現在以擴充一個javascript Test本地對象為例子說明如何擴充webkit js對象：

實作目标: 以下js代碼能夠順利執行

var test = new Test(“aaa”,”bbb”,”ccc”);

test.setValue(“value”);

alert(“ip = “ + test.address + “,mask = “ + test.mask + “,gateway =”+test.gateway + “,value = “ + test.value);

實作步驟:

1.在webkit core目錄(浏覽器根目錄/src/wibkit/Source/core)相應的位置分别建立Test.idl,Test.h,Test.cpp檔案，檔案名和接口名一樣，除非用擴充屬性[ImplementedAs=...] 改變。

在.gni檔案中包含進去，如  core_idl_files.gni并在core.gypi中相應的位置将.idl和c檔案包含進去.

有三種idl：

core 或者 modules，決定在哪個子樹；

main接口或者依賴接口：部分接口沒有.h,.cpp産生。

test接口：不會進入bingding

建構時産生的接口有第四種，generated 或者非靜态

idl接口位置：core的位于

core_idl_files

 variable or in the 

core_dependency_idl_files

 variable

 C++： 

core_files

 variable or an appropriate 

core_*_files

 variable, depending on directory, or 

core_testing_files

 if a testing interface

2..idl檔案是連接配接js對象和c++對象的媒介,首先根據你要設計的js對象的屬性和方法來确定.idl對象,再根據.idl檔案來寫相應的.h 和 .cpp檔案.

現在要新增一個 本地js對象,對象名稱為Test,它的構造方法是傳入三個字元串參數,它有三個可讀寫字元串屬性adress,mask,gateway,一個隻讀字元串屬性value,一個方法為setValue.

那麼Test.idl檔案的内容為.

[

Constructor(DOMString ip,DOMString mask,DOMString gateway),

] interface Test {

readonly attribute DOMString value;

attribute DOMString address;

attribute DOMString mask;

attribute DOMString gateway;

void setValue(DOMString value);

};

在window.idl中加上:

attribute TestConstructor Test; //注意這裡的Test對應的javascript中的Test,如果這裡是myTest,那麼js代碼就是 new myTest(...)

現在寫Test 對應的c++類,它需要實作 static Test * create(String & str1,String &str2,String& str3)供外部調用. 隻讀屬性 value 對應的方法 String value() const; 可讀寫屬性對應的方法 String address() const; void setAddress(const String& ip); //(注意這裡的函數名要與前面.idl檔案聲明的屬性名稱一緻,設定屬性的函數需要在前面加set并将第一個字母大寫,如setAdress函數名一緻),mask , gateway屬性如上. .idl中聲明的方法在c++類中的方法一緻,隻需要照舊聲明一個方法 void setValue(String &value);就行. 好了,隻需要把這些接口實作所有工作就完成了. 接下來就可以編譯運作測試了.

類的實作代碼如下所示:

#ifndef TEST_H

#define TEST_H

#include "wtf/PassRefPtr.h"

#include "core/CoreExport.h"

#include "bindings/core/v8/ScriptWrappable.h"

#include "wtf/RefCounted.h"

#include "wtf/text/WTFString.h"

namespace blink {

class Test : public RefCountedWillBeGarbageCollectedFinalized<Test>,public ScriptWrappable{

DEFINE_WRAPPERTYPEINFO();

public:

virtual ~Test();

static PassRefPtrWillBeRawPtr<Test> create(){

return create( String(""), String(""), String(""));

}

static PassRefPtrWillBeRawPtr<Test> create(String ip,String mask,String gateway );

String address() const;

String mask() const;

String gateway() const;

void setAddress(const String& ip){mIp=ip;}

void setMask(const String& mask){mMask=mask;}

void setGateway(const String& gateway){mGateWay=gateway;}

String value() const;

void setValue(const String& value){mValue=value;}

private:

explicit Test(String,String,String);

String mValue;

String mIp;

String mMask;

String mGateWay;

#endif

二 webkit擴充js内置對象的方法

還是以上面的 Test為例:

1.在Test.idl中将[

] 去除.

2. 在 window.idl 将原來的聲明改為 [Replaceable] readonly attribute Test Test;

3. DomWindow.h中增加Test的虛函數構造方法聲明 virtual Test* test() const {return NULL;}

4.在LocalDOMWindow.h中聲明方法 Test* test() const override,新增變量mutable PersistentWillBeMember<Test> m_test;

5.在LocalDomWindow.cpp中對 test方法做實作

Test* LocalDOMWindow::test() const

{

if (!m_test)

m_test = Test::create();

return m_test.get();

} 

三: 實作原理

Chromium編譯系統會首先去解析test.idl，通過python腳本解析.idl檔案生成相應的v8test.cpp,v8test.h. v8test對象 會調用到我們手動寫的test對象. v8test.cpp對象綁定了js對象相應的屬性和方法,是以在運作時V8解析javascript代碼時能夠找到找到關聯的c++對象上. 運作Test 的js代碼相應的調用步驟是: V8引擎解析js代碼-> v8Test類->Test類.

Web IDL in Blink

Blink developers (non-bindings development): for general IDL use, see Web IDL interfaces; for configuring bindings, see Blink IDL Extended Attributes; for IDL dictionaries use, see IDL dictionaries in Blink. 目錄 1 Overview 2 Basics of IDL 3 Syntax 4 Semantics 4.1 Types 4.2 undefined and null 4.3 Function resolution 5 File organization 5.1 Dependencies 6 IDL extended attribute validator 7 Tests 7.1 Reference tests (run-bindings-tests) 7.2 Behavior tests 8 Where is the bindings code generated? 9 Limitations and improvements 9.1 Syntax error causes infinite loop 9.2 Type checking 10 Bindings development 10.1 Mailing List 11 If working on bindings, you likely wish to join the blink-reviews-bindings mailing list. 11.1 See also Overview ​Web IDL 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, 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 and IDL compiler. 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); }; Let us introduce some terms: The above IDL file describes the  Node  interface. ELEMENT_NODE  is a constant of the  Node parentNode  and  nodeName  are attributes of the  Node appendChild(...) addEventListener(...)  are operations of the  Node type ,  listener useCapture  are arguments of the  addEventListener  operation. [CustomToV8] [TreatReturnedNullStringAs=Null] [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. 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: interface INTERFACE_NAME {     const unsigned long value = 12345;     attribute Node node;     void func(long argument, ...); }; With extended attributes, this looks like: [     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 (Python lex-yacc), an implementation of lex and yacc for Python. A standard-compliant lexer is used (Chromium tools/idl_parser/idl_lexer.py). The parser (Blink bindings/scripts/blink_idl_parser.py) derives from a standard-compliant parser (Chromium 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 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 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: [     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! 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: // 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. Primitive types 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 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 - Dealing with undefined). Behavior on  undefined 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 null  are valid values for basic types, and are automatically converted. Conversion follows ECMAScript type mapping, which generally implements JavaScript Type Conversion, e.g. ToBoolean, ToNumber, ToString. They may be converted to different values, notably  "undefined" "null"  for  DOMString . For numeric types, this can be affected by the extended attributes  [Clamp] [EnforceRange] [Clamp]  changes the value so that it is valid. [EnforceRange]  throws a  TypeError  on these invalid values. for interface types,  undefined 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. 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: 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 null  both correspond to an empty dictionary for union types,  undefined 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 - Dealing with undefined) and not currently implemented. Further, note that in some cases one wants different behavior for  f() 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). 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: 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: function foo(x) { return x } foo() // undefined Note that  foo() 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: 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). See the 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: 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 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, 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. If you want to add a new IDL attribute, you need to add the extended attribute to Source/bindings/IDLExtendedAttributes.txt. add the explanation to the extended attributes document. 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 tests the code generator, including its treatment of extended attributes. Specifically, run_bindings_tests.py compiles the IDL files in bindings/tests/idls, and then compares the results against reference files in 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: 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/CL 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. Behavior tests To test behavior, use web tests, 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, which uses testing/type_conversions.idl. There are also some other IDL files in testing, like 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). 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 for open bugs; please feel free to file bugs or contact bindings developers (members of blink-reviews-bindings, or 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 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). 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). 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 mailing list. See also Web IDL interfaces – overview how-to for Blink developers Blink IDL Extended Attributes – reference for Blink developers and bindings developers IDL build – design doc IDL compiler – design doc

Web IDL interfaces

1 IDL 1.1 Nulls and non-finite numbers 1.2 Union types 1.3 Extended attributes 1.4 Bindings 2 C++ 2.1 Names 2.2 Type information ("ScriptWrappable") 2.2.1 History (ScriptWrappable) 2.3 Garbage Collection 3 See Garbage Collection for Blink C++ objects 4 Build 5 Tests 6 Subtyping 6.1 Technical details 7 Inheritance and code reuse 7.1 Examples 7.1.1 Sharing code with a legacy interface (unprefixing) 7.1.2 Changing inheritance → implements 8 See also 9 External links Web interfaces – exposed as JavaScript objects – are generally specified in Web IDL (Interface Definition Language), a declarative language (sometimes written without the space as WebIDL). This is the language used in standard specifications, and Blink uses IDL files to specify the interface and generate JavaScript bindings (formally, C++ code that the V8 JavaScript virtual machine uses to call Blink itself). Web IDL in Blink is close to the standard, and the resulting bindings use standard conventions to call Blink code, but there are additional features to specify implementation details, primarily Blink IDL extended attributes. To implement a new Web IDL interface in Blink: Interface: write an IDL file:  Foo.idl Implementation: write a C++ file and header:  Foo.cpp, Foo.h Build: add files to the build: edit core_idl_files.gni or modules_idl_files.gni Tests: write unit tests (web tests) in web_tests The bulk of the work is the implementation, secondarily tests. The interface (IDL file) should require minimal work (ideally just copy-and-paste the spec), assuming nothing unusual is being done, and the build can be forgotten about once you've set it up. Details follow. IDL Find spec Create a new file called Foo.idl in the same directory as you will implement the interface, generally Source/core/* or Source/modules/* The initial IDL file should contain: License header Link to the spec Link to tracking bug for implementing the interface IDL "fragment" copied from the spec See Blink IDL: Style for style guide. IDL files contain two types of data: Blink interface – behavior; ideally should agree with spec, but differences from spec should be reflected in the IDL itself Blink implementation – internal-use data, like function names or implementation-specific flags, like memory management. Note that if Blink behavior differs from the spec, the Blink IDL file should reflect Blink behavior. This makes interface differences visible, rather than hiding them in the C++ implementation or bindings generator. Also as a rule, nop data should not be included: if Blink (bindings generator) ignores an IDL keyword or extended attribute, do not include it, as it suggests a difference in behavior when there is none. If this results in a difference from the spec, this is good, as it makes the difference in behavior visible. Initially you likely want to comment out all attributes and operations, uncommenting them as you implement them. Nulls and non-finite numbers Two points to be careful of, and which are often incorrect in specs, particularly older specs, are nullability and non-finite values (infinities and NaN). These are both to ensure correct type checking. If these are incorrect in the spec – for example, a prose specifying behavior on non-finite values, but the IDL not reflecting this – please file a spec bug upstream, and link to it in the IDL file. If null values are valid (for attributes, argument types, or method return values), the type MUST be marked with a ? to indicate nullable, as in  attribute Foo? foo; Note that for arguments (but not attributes or method return values), optional is preferred to nullable (see Re: removeEventListener with only one passed parameter...). Similarly, IEEE floating point allows non-finite numbers (infinities and NaN); if these are valid, the floating point type –  float  or  double  – MUST be marked as  unrestricted  as in  unrestricted float unrestricted double  – the bare  float double  means finite floating point. Ref: double, unrestricted double, Type mapping: double, Type mapping: unrestricted double Union types Many older specs use overloading when a union type argument would be clearer. Please match spec, but file a spec bug for these and link to it. For example: // FIXME: should be void bar((long or Foo) foo);　https://www.w3.org/Bugs/Public/show_bug.cgi?id=123 void bar(long foo); void bar(Foo foo); Also, beware that you can't have multiple nullable arguments in the distinguishing position in an overload, as these are not distinguishing (what does  null  resolve to?). This is best resolved by using a union type if possible; otherwise make sure to mark only one overload as having a nullable argument in that position. Don't do this: void zork(Foo? x); void zork(Bar? x); // What does zork(null) resolve to? Instead do this: void zork(Foo? x); void zork(Bar x); ...but preferably this: void zork((Foo or Bar)? x); Extended attributes You will often need to add Blink-specific extended attributes to specify implementation details. Please comment extended attributes – why do you need special behavior? Bindings See Web IDL in Blink. C++ Bindings code assumes that a C++ class exists, with methods for each attribute or operation (with some exceptions). Attributes are implemented as properties, meaning that while in the JavaScript interface these are read and written as attributes, in C++ these are read and written by getter and setter methods. For cases where an IDL attribute reflects a content attribute, you do not need to write boilerplate methods to call  getAttribute() setAttribute().  Instead, use the  [Reflect]  extended attribute, and these calls will automatically be generated inline in the bindings code, with optimizations in some cases. However, if you wish to access these attributes from C++ code (say in another class), not just from JavaScript, you will need to write a getter and/or a setter, as necessary. Names The class and methods have default names, which can be overridden by the  [ImplementedAs]  extended attribute; this is strongly discouraged, and method names should align with the spec unless there is very good reason for them to differ (this is sometimes necessary when there is a conflict, say when inheriting another interface). Given an IDL file Foo.idl: interface Foo {     attribute long a;     attribute DOMString cssText;     void f();     void f(long arg);     void g(optional long arg); }; ...a minimal header file Foo.h illustrating this is: class Foo { public:     int a();     void setA(int);     String cssText();     void setCSSText(const String&);     void f();     void f(int);     void g();     void g(int);     // Alternatively, can use default arguments:     // void f(int arg=0); }; IDL interfaces assume a class of the same name:  class Foo IDL attributes call a getter of the same name, and setter with set prepended and capitalization fixed:  a() setA() . This correctly capitalizes acronyms, so the setter for cssText is  setCSSText() . (If you need to add acronyms, these are set in  v8_common.ACRONYMS .) IDL operations call a C++ method of the same name:  f() Web IDL overloading and IDL optional arguments without default values map directly to C++ overloading (optional arguments without default values correspond to an overload either including or excluding the argument). IDL optional arguments with default values map to C++ calls with these values filled in, and thus do not require C++ overloading. C++ default values SHOULD NOT be used unless necessary (not yet supported by compiler). However, currently IDL default values are only partly supported (Bug 258153), and thus C++ default values are used. There are various complicated corner cases, like non-trailing optional arguments without defaults, like foo(optional long x, optional long y = 0); Type information ("ScriptWrappable") Blink objects that are visible in JavaScript need type information, fundamentally because JavaScript is dynamically typed (so values have type), concretely because the bindings code uses type introspection for dynamic dispatch (function resolution of bindings functions): given a C++ object (representing the implementation of a JavaScript object), accessing it from V8 requires calling the correct C++ binding methods, which requires knowing its JavaScript type (i.e., the IDL interface type). Blink does not use C++ run-time type information (RTTI), and thus the type information must be stored separately. There are various ways this is done, most simply (for Blink developers) by the C++ class inheriting  ScriptWrappable  and placing  DEFINE_WRAPPERTYPEINFO  in the class declaration. Stylistically  ScriptWrappable  should be the last class, or at least after more interesting classes, and should be directly inherited by the class (not indirectly from a more distant ancestor). Explicitly: Foo.h: #ifndef Foo_h #define Foo_h #include "bindings/v8/ScriptWrappable.h" namespace WebCore { class Foo FINAL : /* maybe others */ public ScriptWrappable {     DEFINE_WRAPPERTYPEINFO();     // ... }; } // namespace WebCore #endif Foo_h In case of C++ inheritance, it's preferable to avoid inheriting ScriptWrappable indirectly, most simply because this creates overhead on a redundant write. In many cases this can be avoided by having an abstract base class that both concrete classes inherit. Stylistically, FIXME However, in some cases – notably if both a base class and a derived class implement JS interface types (say, if there is IDL inheritance and the C++ inheritance is the same) – you will need to call  ScriptWrappable::init  both in the base class and the derived class. Thus, to avoid this: class Foo FINAL : public Bar,  public ScriptWrappable  { /* ... */ }; Bar.h: class Bar : public ScriptWrappable { /* ... */ }; ...instead use an abstract base class, and have both concrete classes inherit  ScriptWrappable  directly: class Foo FINAL : public FooBarBase,  class Bar FINAL : public FooBarBase,  FooBarBase.h: class FooBarBase { /* ... */ }; History (ScriptWrappable) [webkit-dev] Making more use of ScriptWrappable (Adam Barth, 2012 Nov) Garbage Collection See Garbage Collection for Blink C++ objects Build You need to list the  .idl  file and  .h/.cpp  files in the correct GN variable so that they will be built (bindings generated, Blink code compiled.) IDL files to be processed are listed in .gni (GN Include) files. For core files, this is core_idl_files.gni. There are 3 dichotomies in these  .idl  files, which affect where you list them in the build: core vs. modules – which subtree they are in main interface vs. dependency – partial interfaces and implemented interfaces do not have individual bindings ( .h/.cpp ) generated testing or not – testing interfaces do not appear in the aggregate bindings If you generate IDL files at build time, there is a 4th dichotomy: generated or not (static) – generated files need to be treated differently by the build system (passed as command line arguments, rather than listed in a generated file, since generated files are in the build directory, which is only known at build time, not GN time). For core interfaces, the IDL files are listed in the  core_idl_files core_dependency_idl_files  variable, if the IDL file is a partial interface or the target (right side of) an  implements  statement. This distinction is because partial interfaces and implemented interfaces do not have their own bindings generated, so these IDL files are not directly compiled. Testing files are listed in the  core_testing_idl_files  variable instead; there are currently no core testing dependency files. The C++ files should be listed in the  core_files core_*_files core_testing_files  if a testing interface. Modules files are analogous, and placed in modules_idl_files.gni. There are currently no modules testing interface files, but there are modules testing dependency files, which are listed in  modules_dependency_idl_files modules_testing_files Make sure to test: default objects – create a new object and pass as argument or assign to an attribute undefined/null  – if passed to nullable arguments or set to nullable attributes, should not throw; if passed to non-nullable arguments or set to non-nullable attributes, should throw but not crash Subtyping There are three mechanisms for subtyping in IDL: inheritance:  interface A : B { ... }; implements statements:  A implements B; partial interface:  partial interface A { ... }; The corresponding C++ implementations are as follows, here illustrated for  attribute T foo; inheritance: handled by JavaScript, but often have corresponding C++ inheritance; one of: class A { ... }; class A : B { ... }; implements: C++ class must implement methods, either itself or via inheritance; one of: class A { public: T foo(); void setFoo(...); ... }; class A : B { ... }; unless there is a layering violation (an interface in  modules  implemented in  core ), in which case put  [TreatAsPartial]  on the implemented interface definition and implement as static member functions, as in partial interface. partial interface: implemented as static member functions in an unrelated class: class B { static T foo(A& a); static void setFoo(A& a, ...); ... }; IDL files SHOULD agree with spec, and almost always MUST do so. It is not ok to change the kind of subtyping or move members between interfaces, and violations SHOULD or MUST be fixed: Inheritance is visible to JavaScript (in the prototype chain), so it MUST be correct (it is NOT ok to have non-spec inheritance relationships). The distinction between "member of (main) interface definition, member of implemented interface, member of partial interface" is not visible in JavaScript (these are all just properties of the prototype object), so while this SHOULD agree with spec (so Blink IDL agrees with IDL in the spec), this is not strictly required. The distinction between "member of (child) interface" and "member of parent interface" is visible in JavaScript (as property on prototype object corresponding to (child) interface vs. property on prototype object corresponding to parent interface), and thus MUST be correct (it is NOT ok to move members between an interface and a parent if this disagrees with spec). Technical details While members of an interface definition, members of implemented interface, and members of partial interfaces are identical for JavaScript, partial interface members – and members of certain implemented interfaces, namely those with the  [TreatAsPartial]  extended attribute – are treated differently internally in Blink (see below). Inheritance and implements are both interface inheritance. JavaScript has single inheritance, and IDL inheritance corresponds to JavaScript inheritance, while IDL  implements  provides multiple inheritance in IDL, which does not correspond to inheritance in JavaScript. In both cases, by spec, members of the inherited or implemented interface must be implemented on the JavaScript object implementing the interface. Concretely, members of inherited interfaces are implemented as properties on the prototype object of the parent interface, while members of implemented interfaces are implemented as properties of the implementing interface. In C++, members of an interface definition and members of implemented interfaces are implemented on the C++ object (referred to as the parameter or variable  impl ) implementing the JavaScript object. Specifically this is done in the Blink class corresponding to the IDL interface or a base class – the C++ hierarchy is invisible to both JavaScript and the bindings. Implementation-wise, inheritance and implements differ in two ways: Inheritance sets the prototype object (this is visible in JavaScript via  getPrototypeOf );  implements  does not. Bindings are not generated for inherited members (JavaScript dispatches these to the parent prototype), but are generated for implemented members. For simplicity, in the wrapper (used by V8 to call Blink) the bindings just treat members of implemented interfaces and partial interfaces as if they were part of the main interface: there is no multiple inheritance in the bindings implementation. If (IDL) interface A inherits from interface B, then usually (C++) class A inherits from class B, meaning that: interface A : B { /* ... */ }; is usually implemented as: class A : B { /* ... */ }; ...or perhaps: class A : C { /* ... */ }; class C : B { /* ... */ }; However, the bindings are agnostic about this, and simply set the prototype in the wrapper object to be the inherited interface (concretely, sets the parentClass attribute in the WrapperTypeInfo of the class's bindings). Dispatch is thus done in JavaScript. "A implements B;" should mean that members declared in (IDL) interface B are members of (C++) classes implementing A. impl. Partial interfaces formally are type extension (external type extension, since specified in a separate place from the original definition), and in principle are simply part of the interface, just defined separately, as a convenience for spec authors. However in practice, members of partial interfaces are not assumed to be implemented on the C++ object ( impl ), and are not defined in the Blink class implementing the interface. Instead, they are implemented as static members of a separate class, which take  impl  as their first argument. This is done because in practice, partial interfaces are type extensions, which often only used in subtypes or are deactivated (via conditionals or as runtime enabled features), and we do not want to bloat the main Blink class to include these. Further, in some cases we must use type extension (static methods) for implemented interfaces as well. This is due to componentization in Blink (see Browser Components), currently  core  versus  modules.  Code in  core  cannot inherit from code in  modules,  and thus if an interface in  core  implements an interface in  modules,  this must be implemented via type extension (static methods in  modules ). This is an exceptional case, and indicates that Blink's internal layering (componentization) disagrees with the layering implied by the IDL specs, and formally should be resolved by moving the relevant interface from  modules  to  core.  This is not always possible or desirable (for internal implementation reasons), and thus static methods can be specified via the  [TreatAsPartial]  extended attribute on the implemented interface. Inheritance and code reuse IDL has single inheritance, which maps directly to JavaScript inheritance (prototype chain). C++ has multiple inheritance, and the two hierarchies need not be related. FIXME: There are issues if a C++ class inherits from another C++ class that implements an IDL interface, as . downcasting IDL has 3 mechanisms for combining interfaces: (Single) inheritance implements partial interface Examples Sharing code with a legacy interface (unprefixing) ... Changing inheritance → implements Converting a parent to the target of an implements Other Blink interfaces, not standard Web IDL interfaces: Public C++ API: C++ API used by C++ programs embedding Blink (not JavaScript), including the (C++) "web API" Implementing a new extension API: Chrome extensions (JavaScript interfaces used by extensions), also use a dialect of Web IDL for describing interfaces External links For reference, documentation by other projects. Mozilla Developer Network (MDN) Web API reference WebIDL bindings IDL interface rules W3C Wiki: Web IDL

Implementing a new extension API

Proposal See API Proposals (New APIs Start Here). So you want to add the Widgets API. Let's call it widgets. Defining the Interface How will extensions declare their intent to use widgets? You need to decide this now. In other words, what will a user of widgets need to write in their manifest? Typically this will be either via a permission string or manifest entry. There is no need for both. By convention it should be called "widgets". Use a manifest entry for declarative style APIs, or when you need to express some sort of rich structure. For example, commands.   "name": "Demo widget extension",   "widgets": {     "foo": "bar",     "baz": "qux"   }   ... Use a permission string for procedural APIs, typically those which are just a collection of functions. Most APIs are of this form. For example, storage.   "permissions": [..., "widgets", ...] There are exceptions: Some APIs are integral parts of the platform (e.g. runtime, app.window, etc) and require no declaration. Some older APIs use object permissions rather than strings, such as fileSystem. This is deprecated. Use a manifest entry instead. Tell the extensions platform about widgets Firstly decide, can your API be applied to any platform built on the web, or does it only make sense for Chrome? Examples of the former: storage, messaging. Examples of the latter: browserAction, bookmarks. A good clue is whether you need to #include anything from chrome. If it applies to any platform, widgets should be implemented in the extensions module (src/extensions). If it's Chrome only, widgets should be implemented in Chrome (src/chrome/common/extensions and src/chrome/browser/extensions, etc). If in doubt, try to implement it in src/extensions. From here, all files here are relative to either extensions/common/api or chrome/common/extensions/api: First, add an entry in _api_features.json. This tells the extensions platform about when your API should be available (anywhere? only in extension processes?), and what they need to do to use it (do they need a permission? a manifest entry?). If you're using a manifest entry, use "manifest:widgets" as the dependency. If you're using a permission string, use "permission:widgets" as the dependency. Second, add an entry to either _manifest_feature.json or _permission_features.json. This tells the platform how to interpret "widgets" when it encounters it as either a manifest entry or a permission. What is it available to (extensions? apps? both?), and importantly what channel is it available in (dev? beta? stable?). New extension APIs MUST start in dev (although if they're unimplemented then trunk is advisable). New extension APIs MUST start in dev (just repeating it). Write a schema for widgets Extension APIs can be defined in either IDL (widgets.idl) or JSON Schema (widgets.json). IDL is much more concise, but doesn't include some of the advanced features supported by JSON Schema. You probably want IDL, though be warned IDL syntax errors occasionally cause the compiler to never terminate. Fourth, list the schema in schemas.gypi, which tells the build system to generate a bunch of boilerplate for you in <build_dir>/gen/extensions/common/api or <build_dir>/gen/chrome/common/extensions/api: models for your API, and the glue to hook into your implementation. Finally, add some documentation: Adding documentation Adding documentation is very simple: Write a summary for your API and put it in chrome/common/extensions/docs/templates/intros/myapi.html.  Create the publicly accessible template(s) in chrome/common/extensions/docs/templates/public/{extension,apps}/myapi.html. Whichever of extensions and/or apps you add an HTML file in depends on which platform can access your API. Each will look something like: {{+partials.standard_extensions_api api:apis.extensions.myapi intro:intros.myapi /}} (or apps). C++ implementation The actual C++ implementation will typically live in extensions/browser/api/myapi or chrome/browser/extensions/api/myapi (as mentioned above, the magic glue is generated for you). Functions Extension APIs are implemented as subclasses of ExtensionFunction from extensions/browser/extension_function.h. Use DECLARE_EXTENSION_FUNCTION to declare the JavaScript identifier for the function. Implement ExtensionFunction::Run. The comments on that method explain how to implement it. Note: use EXTENSION_FUNCTION_VALIDATE to validate input arguments, which are placed in args_. Failing this check kills the renderer, so the idiom for this is catching bugs in the renderer (for example: schema validation errors). Add your implementation files to chrome/chrome_browser_extensions.gypi. Model generation  Your C++ implementation must live in extensions/browser/api/myapi/myapi_api.h/cc or chrome/browser/extensions/api/myapi/myapi_api.h/cc (depending on where it was declared).This is so that the code generator can find the header file defining your extension function implementations. Remember to add your source files to chrome/chrome_browser_extensions.gypi. In your header file, include extensions/common/api/myapi.h or chrome/common/extensions/api/myapi.h to use the generated model. This comes from a code-generated file that lives under e.g. out/Debug/gen/chrome/common/extensions/api. Let's say we have the following IDL (or equivalent JSON schema): // High-level description of your API. This will appear in various places in the docs. namespace myapi {   dictionary BazOptions {     // Describes what the id argument means.     long id;     // Describes what the s argument means.     DOMString s;   };   dictionary BazResult {     long x;     long y;   callback BazCallback = void (BazResult result);   interface Functions {     // An interesting comment describing what the baz operation is.     // Note that this function can take multiple input arguments, including things like     // long and DOMString, but they have been elided for simplicity.     static void doBaz(BazOptions options, BazCallback callback); A simple C++ implementation might look like this: namespace extensions { // You must follow a naming convention which is ApiNameFunctionNameFunction, // in this case MyapiDoBazFunction. This is so that the generated code // can find your implementation. class MyapiDoBazFunction : public AsyncExtensionFunction {  public:   virtual ~MyapiDoBazFunction () {}  private:   // The MYAPI_DOBAZ entry is an enum you add right before ENUM_BOUNDARY   // in chrome/browser/extensions/extension_function_histogram_value.h   DECLARE_EXTENSION_FUNCTION("myapi.doBaz", MYAPI_DOBAZ);   virtual ResponseAction Run() OVERRIDE {     // Args are passed in via the args_ member as a base::ListValue.     // Use the convenience member of the glue class to easily parse it.     std::unique_ptr<api::myapi::DoBaz::Params> params(         api::myapi::DoBaz::Params::Create(*args_));     EXTENSION_FUNCTION_VALIDATE(params.get());     api::myapi::BazResult result;     result.x = params->options.id;     base::StringToInt(params->options.s, &result.y);     // Responds to the caller right, but see comments on     // ExtensionFunction::Run() for other ways to respond to messages.     return RespondNow(ArgumentList(result.ToValue()));  }  // namespace extensions ExtensionFunction is refcounted and instantiated once per call to that extension function, so use base::Bind(this) to ensure it's kept alive (or use AddRef...Release if that's not possible for some reason). Events Use ExtensionEventRouter (on the UI thread) to dispatch events to extensions. Prefer the versions that allow you to pass in base::Value rather than a JSON serialized format. Event names are auto-generated in the API file (e.g. chrome/common/extensions/api/myapi.h). In the un-common case where an event is not defined in IDL or json, the corresponding event name should be defined in chrome/browser/extensions/event_names.h. As with extension functions, it generates some C++ glue classes. Let's say we have the following IDL (or equivalent JSON Schema):   dictionary Foo {      // This comment should describe what the id parameter is for.      long id;      // This comment should describe what the bar parameter is for.      DOMString bar;   interface Events {     // Fired when something interesting has happened.     // |foo|: The details of the interesting event.     static void onInterestingEvent(Foo foo); To use the generated glue in C++: DCHECK(BrowserThread::CurrentlyOn(BrowserThread::UI)); api::myapi::Foo foo; foo.id = 5; foo.bar = "hello world"; ExtensionSystem::Get(profile)->event_router()->DispatchEventToExtension(     extension_id,     api::myapi::OnInterestingEvent::kEventName,     *api::myapi::OnInterestingEvent::Create(foo),     profile,     GURL()); Permissions By default, extension APIs should require a permission named the same as the API namespace.  New permissions are added in ExtensionAPIPermissions::GetAllPermissions() in extensions/common/permissions/extensions_api_permissions.cc or in ChromeAPIPermissions::GetAllPermissions() in  chrome/common/extensions/permissions/chrome_api_permissions.cc. You may also need to modify api_permission.h and chrome_permission_message_rules.cc in those directories; see how it's done for other permissions. Advanced Extension Functionality Custom Bindings Custom JS bindings go in chrome/renderer/resources/extensions/*.js. These are necessary for doing anything special: synchronous API functions, functions bound to types, anything renderer-side. (If it's a common enough operation, please send us patches to do it automatically as part of the bindings generation :). New Manifest Sections If your API requires a new manifest section: Add a schema for the manifest entry to chrome/common/extensions/api/manifest_types.json (e.g. Widgets). This is the JSON Schema format. See "Write a schema for widgets". Add the name of the manifest entry to chrome/common/extensions/api/_manifest_features.json and declare when it's available. See "Tell the extensions platform about widgets". Add a ManifestHandler implementation in chrome/common/extensions/manifest_handlers (e.g. chrome/common/extensions/widgets_handler.cc/h). Your implementation can use the model that has been generated from the schema in manifest_types.json And of course, test it. If your manifest section requires permission messages and/or custom permissions, add a ManifestPermission implementation. See "sockets_manifest_handler" for an example. The code which handles the externally_connectable manifest key is a good place to start. Testing Your Implementation Make sure it has tests. Like all of Chrome, we prefer unit tests to integration tests. There is a relatively new mini framework for unit tests in chrome/browser/extensions/extension_function_test_utils.h. Hopefully it meets your needs. If not, there is the older API tests for integration tests. Iterating Create an example extension that uses your API and add it to chrome/common/extensions/docs/examples Ask someone else (preferably someone in chrome-devrel@ or chrome-extensions-team@) to make a second example extension Iterate based on how those examples went Make sure that your API is functional on all of Chrome's platforms that have access to the web store and that all tests are enabled on all platforms Announce the dev channel API to the community by sending mail to [email protected] and a blog post if appropriate Encourage community feedback (ask chrome-extensions-team@ for ideas here) Iterate on the API based on community feedback In general, an API should be on dev channel for at least one full release cycle before moving on to the next phase Going to Stable Follow the Going Live Phase instructions.