WebKitIDLWebKit.docx
- 文档编号:23056667
- 上传时间:2023-04-30
- 格式:DOCX
- 页数:21
- 大小:20.73KB
WebKitIDLWebKit.docx
《WebKitIDLWebKit.docx》由会员分享,可在线阅读,更多相关《WebKitIDLWebKit.docx(21页珍藏版)》请在冰豆网上搜索。
WebKitIDLWebKit
WebKitIDL–WebKit
Overview
TheWebIDLisalanguagethatdefineshowWebCoreinterfacesareboundtoexternallanguagessuchasJavaScriptCore,
ObjC,GObjectandCPP.YouneedtowriteIDLfiles(e.g.
XMLHttpRequest.idl,Element.idl,etc)toexposeWebCoreinterfacesto
thoseexternallanguages.WhenWebKitisbuilt,theIDLfilesare
parsed,andthecodetobindWebCoreimplementationsandJavaScriptCore,ObjC,GObjectandCPPinterfacesisautomaticallygenerated.
ThisdocumentdescribespracticalinformationabouthowtheIDLbindings
workandhowyoucanwriteIDLfilesinWebKit.ThesyntaxofIDLfiles
isfairlywelldocumentedintheWebIDLspec,
butitistooformaltoread:
-)andthereareseveraldifferences
betweentheWebIDLspecandtheWebKitIDLduetoimplementation
issues.
BasicsofIDL
HereisanexampleofIDLfiles:
modulecore{
[
CustomToJSObject
]interfaceNode{
constunsignedshortELEMENT_NODE=1;
attributeNodeparentNode;
[TreatReturnedNullStringAs=Null]attributeDOMStringnodeName;
[Custom]NodeappendChild([CustomReturn]NodenewChild);
voidaddEventListener(DOMStringtype,EventListenerlistener,optionalbooleanuseCapture);
};
}
Letusintroducesometerminologies:
TheaboveIDLfiledescribestheNodeinterface.
ELEMENT_NODEisaconstantoftheNodeinterface.
parentNodeandnodeNameareattributesoftheNodeinterface.
appendChild(...)andaddEventListener(...)aremethodsoftheNodeinterface.
type,listeneranduseCaptureareparametersoftheNodeinterface.
[CustomToJSObject],[TreatReturnedNullStringAs=Null],[Custom]and[CustomReturn]areIDLattributes.
Note:
TheseterminologiesarenotalignedwiththeWebIDLspec.
IntheWebIDLspec,a'method'iscalledan'operation'.
Thereisnodistinctionbetweenan'attribute'anda'parameter'(a'parameter'istreatedasan'attribute').
Thekeypointsareasfollows:
AnIDLfilecontrolshowthebindingscodebetweenJavaScript
engine(orObjC,GObject,CPP)andtheWebKitimplementationis
generated.
IDLattributesenableyoutocontrolthebindingscodemoreindetail.
Thereare90~IDLattributesandtheirrolesareexplainedinthesubsequentsections.
IDLattributescanbespecifiedoninterfaces,methods,attributesandparameters.
WhereeachIDLattributecanbespecifiedonisdefinedpereachIDLattribute.
Thisisalsoexplainedinthesubsequentsections.
AtemplateofanIDLfileisasfollows:
moduleMODULE_NAME{
[
IDL_ATTRIBUTE_ON_INTERFACE1,
IDL_ATTRIBUTE_ON_INTERFACE2,
...
]interfaceINTERFACE_NAME{
constunsignedlongvalue=12345;
[IDL_ATTRIBUTE_ON_ATTRIBUTE1,IDL_ATTRIBUTE_ON_ATTRIBUTE2,...]attributeNodenode;
[IDL_ATTRIBUTE_ON_METHOD1,IDL_ATTRIBUTE_ON_METHOD2,...]voidfunc([IDL_ATTRIBUTE_ON_PARAMETER1,IDL_ATTRIBUTE_ON_PARAMETER2,...]intparam,...);
};
}
IfthereisnoIDLattributesoninterfaces,theIDLfilejustlookslikethis:
moduleMODULE_NAME{
interfaceINTERFACE_NAME{
constunsignedlongvalue=12345;
[IDL_ATTRIBUTE_ON_ATTRIBUTE1,IDL_ATTRIBUTE_ON_ATTRIBUTE2,...]attributeNodenode;
[IDL_ATTRIBUTE_ON_METHOD1,IDL_ATTRIBUTE_ON_METHOD2,...]voidfunc([IDL_ATTRIBUTE_ON_PARAMETER1,IDL_ATTRIBUTE_ON_PARAMETER2,...]intparam,...);
};
}
IDLattributechecker
PreviouslytherehadbeenmanybugscausedbytyposofIDLattributesinIDLfiles.
Toavoidsuchbugs,theIDLattributecheckerisintroducedtotheWebKitbuildflow
tocheckifalltheIDLattributesusedinIDLfilesareimplementedincodegenerators.
IfyouuseanIDLattributenotimplementedincodegenerators,theIDLattributecheckerfails,andtheWebKitbuildfails.
AlistofIDLattributesimplementedincodegeneratorsisdescribedinWebCore/bindings/scripts/IDLAttributes.txt.
IfyouwanttoaddanewIDLattribute,youneedto
addtheIDLattributetoWebCore/bindings/scripts/IDLAttributes.txt.
addtheexplanationtothisdocument.
addtestcasestorun-bindings-tests(explainedbelow).
run-bindings-tests
Tools/Scripts/run-bindings-teststestsIDLattributes.
Specifically,run-bindings-testsreads
WebCore/bindings/scripts/test/*.idl,
andthengeneratesbindingscodeto
WebCore/bindings/scripts/test/{JS,ObjC,GObject,CPP}/*.
Forexample,run-bindings-testsreads
WebCore/bindings/scripts/test/TestObj.idl,
andthengeneratesbindingscodeto
WebCore/bindings/scripts/test/JS/JSTestObj.h,
WebCore/bindings/scripts/test/JS/JSTestObj.cpp,etc.
IfyouchangethebehaviorofcodegeneratorsoraddanewIDLattribute,
pleaseaddtestcasestoWebCore/bindings/scripts/test/*.idl.
Youcanresettherun-bindings-testsresultsusingthe--reset-resultsoption:
$./Tools/Scripts/run-bindings-tests--reset-results
Theobjectiveofrun-bindings-testsistoshowyouandreviewershowthecodegenerationischangedbyyourpatch.
Ifyouchangethebehaviorofcodegenerators,pleaseupdatetheresultsofrun-bindings-tests.
Thatbeingsaid,run-bindings-testsisjustforshowingthechangetoyouandreviewers,
andthetestfailureisnotcriticalfortheWebKitbuild.
Peoplehavebeenlikelytoforgettoupdatetherun-bindings-testsresultsinfact.
Therefore,buildbotsdonottreatthetestfailureasafailure.
Inthisway,therun-bindings-testsresultsintheWebKitrepositoryaresometimeswrong.
Ifyoufindit,pleaserebaselinetherun-bindings-testsbeforemakingyourpatch.
Ifyoumakeyourpatchwithoutrebaseliningthetestresults,
therun-bindings-testsresultswillincludethechangesthathadbeencausedbypreviouspatches,
whichwouldbeunreadableforyouandreviewers.
Anyway,ideallyallpeopleshouldupdatetherun-bindings-testsresultsiftheirpatchchangesthebehaviorofcodegenerators.
Whereisthebindingscodegenerated?
ByreadingthisdocumentyoucanlearnhowIDLattributeswork.
However,thebestpracticetounderstandIDLattributesistotrytouse
someIDLattributesandwatchwhatkindofbindingscodeisgenerated.
IfyoutouchanyIDLfile,allIDLfilesarerebuilt.
Thecodegenerationisdoneattheveryearlystepofthe./webkit-buildcommand,
soyoucanobtainthegeneratedcodein1minute.
IncaseofXXX.idlintheReleasebuild,thebindingscodeisgenerated
inthefollowingfiles("Release"becomes"Debug"intheDebugbuild).
JavaScriptCore:
WebKitBuild/Release/DerivedSources/WebCore/JSXXX.h
WebKitBuild/Release/DerivedSources/WebCore/JSXXX.cpp
ObjC:
WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.h
WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.mm
GObject:
WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.h
WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.cpp
CPP:
WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.h
WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.cpp
BasicnamingrulesofIDLattributes
ThereareafewrulesinnamingIDLattributes:
AnameshouldbealignedwiththeWebIDLspecasmuchaspossible.
JavaScriptCore-specificIDLattributesareprefixedby"JS".
ObjC-specificIDLattributesareprefixedby"ObjC".
GObject-specificIDLattributesareprefixedby"GObject".
CPP-specificIDLattributesareprefixedby"CPP".
IDLattributesforcustombindingsareprefixedby"Custom".
Forexample,[JSNoStaticTables],[CustomGetter],etc.
IDLattributes
Inthefollowingexplanations,(i),(m),(a)or(p)meansthatagiven
IDLattributecanbespecifiedoninterfaces,methods,attributesand
parameters,respectively.Forexample,(a,p)meansthattheIDL
attributecanbespecifiedonattributesandparameters.
[TreatNullAs](a,p),[TreatUndefinedAs](a,p)
ThespecofTreatNullAs(Note:
TheWebKitbehaviorexplainedbelowisdifferentfromthespec)
ThespecofTreatUndefinedAs(Note:
TheWebKitbehaviorexplainedbelowisdifferentfromthespec)
Summary:
TheycontrolthebehaviorwhenaJavaScriptnullorundefinedispassedtoaDOMStringattributeorparameter.
Usage:
Thepossibleusageis[TreatNullAs=NullString]or[TreatUndefinedAs=NullString].
TheycanbespecifiedonDOMStringattributesorDOMStringparametersonly:
[TreatNullAs=NullString]attributeDOMStringstr;
voidfunc([TreatNullAs=NullString,TreatUndefinedAs=NullString]DOMStringstr);
[TreatNullAs=NullString]indicatesthatifaJavaScriptnullispassedtotheattributeorparameter,
thenitisconvertedtoaWebKitnullstring,forwhichbothString:
:
IsEmpty()andString:
:
IsNull()willreturntrue.
Without[TreatNullAs=NullString],aJavaScriptnullisconvertedtoaWebKitstring"null".
[TreatNullAs=NullString]inWebKitcorrespondsto[TreatNullAs=EmptyString]intheWebIDLspec.
Unlessthespecspecifies[TreatNullAs=EmptyString],youshouldnotspecify[TreatNullAs=NullString]inWebKit.
[TreatUndefinedAs=NullString]indicatesthatifaJavaScriptundefinedispassedtotheattributeorparameter,
thenitisconvertedtoaWebKitnullstring,forwhichbothString:
:
IsEmpty()andString:
:
IsNull()willreturntrue.
Without[TreatUndefinedAs=NullString],aJavaScriptundefinedisconvertedtoaWebKitstring"undefined".
[TreatUndefinedAs=NullString]inWebKitcorrespondsto[TreatUndefinedAs=EmptyString]intheWebIDLspec.
Unlessthespecspecifies[TreatUndefinedAs=EmptyString],youshouldnotspecify[TreatUndefinedAs=NullString]inWebKit.
Note:
Fornowthesoleusageof[TreatUndefinedAs=NullString]isnotallowed.
[TreatUndefinedAs=NullString]mustbeusedwith[TreatNullAs=NullString],i.e.[TreatNullAs=NullString,TreatUndefinedAs=NullString].
[TreatReturnedNullStringAs](m,a)
Summary:
[TreatReturnedNullStringAs]controlsthebehaviorwhenaWebKitnullstringisreturnedfromtheWebCoreimplementation.
Usage:
Thepossibleusageis[TreatReturnedNullStringAs=Null],[TreatReturnedNullStringAs=Und
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- WebKitIDL WebKit