[Webkit-unassigned] [Bug 101224] [GTK] Check DOM bindings API compatibility while building

[bugzilla-daemon at webkit.org]

https://bugs.webkit.org/show_bug.cgi?id=101224





--- Comment #7 from Carlos Garcia Campos <cgarcia at igalia.com>  2012-11-05 23:49:43 PST ---
(In reply to comment #6)
> (In reply to comment #3)
> 
> > There aren't four, there's one symbols file per DOM object. This is because the generator script is called per DOM object. We could use a single file, and append the symbols, but then we would need rules in the makefile to delete the file before generating the bindings, and append the symbols for the static sources, so it would be more complicated. 
> 
> This is not what I'm seeing in the patch. I see four .symbols files. One for EventTarget, one for DOMObject, one for the custom APIs and one for the rest of the DOM objects. It seems like this division is based on the internal details of how the bindings are generated.

DOM bindings are a collection of wrapper objects, most of them are auto-generated at build time and two (EvenTarget and Object) are static, manually written and are in the source tree. Custom is a special case because it's not a DOM object, but it contains public methods too. 

This division is an implementation detail, in the end what we have is a collection of objects like any other API. If you look at the current Makefile, we have to manually copy the static sources to the derived sources dir during building so that all files are handled the same way (it makes everything easier). 

I'm doing the same here, for autogenerated objects, the .symbols file is generated by the same script that creates the code, and for static code, the .symbols file is created manually. In the end, we have a .symbols file per object (and one for custom), so we don't need to handle the static code as a separate case anymore.

When all bindings have been generated, a .symbols file is created concatenating all .symbols file, and it's used to compare with the .symbols file we keep in the source tree (all others are temporary files in the build dir). This is one of the goals of the goals of this. If there's an API break (not necessarily any change in the API but only an API incompatible change) the build finishes early showing a diff between the .symbols file in the source tree and the concatenation of all other .symbols files.

> I'm not sure that's the kind of division we want in the API docs. For instance, a section per DOM object or everything in one section seems more logical.

A -sections.txt file contains a section per object in the API, something like this:

<SECTION>
<FILE>WebKitDOMDocument</FILE>
<TITLE>WebKitDOMDocument</TITLE>
WebKitDOMDocument
webkit_dom_document_create_element
webkit_dom_document_create_document_fragment
....

<SUBSECTION Standard>
WEBKIT_TYPE_DOM_DOCUMENT
WEBKIT_DOM_DOCUMENT
WEBKIT_DOM_IS_DOCUMENT
WEBKIT_DOM_DOCUMENT_CLASS
WEBKIT_DOM_IS_DOCUMENT_CLASS

<SUBSECTION Private>
webkit_dom_document_get_type
</SECTION>
.....

This file doesn't necessarily means there will be a section per object in the docs, that's organized in the docs.sgml file. We could have a whole DOM bindings subsection in the docs with all the DOM API. Please, look at other gtk-doc projects or how we create the docs for WebKit1 and WEbKit2 APIs.

> Perhaps it's cleaner to dump all symbols into the same file. The script could even operate like the bindings tests, which handles both the step of generating the files (via --reset-results) and failing if it changes otherwise.

Yes, I thought about adding --reset-results to gobject-check-api, to manually update the results, but I'm still not sure how to handle the results update yet, see comment #1.

> Another idea is that we could just roll this into run-gtk-tests -- the pre-existing GTk+ API test suite. That's fewer build rules and 'make test' works automatically.

But we don't want to break make test or make check, but make all, and as soon as possible.

-- 
Configure bugmail: https://bugs.webkit.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the assignee for the bug.