[libvirt] Update libvirt API and refs XML files

[Daniel P. Berrange]

On Fri, Oct 02, 2009 at 12:16:36PM +0100, Daniel P. Berrange wrote:
> On Thu, Oct 01, 2009 at 01:33:50PM +0200, Daniel Veillard wrote:
> > On Thu, Oct 01, 2009 at 12:32:51PM +0200, Chris Lalancette wrote:
> > > Matthias Bolte wrote:
> > > > Commit 47c8709564ac3f2ec5b4a3830ac213e69b4a44d5 "Fix up a few typos in
> > > > the tree" triggered changes in docs/libvirt-api.xml and
> > > > docs/libvirt-refs.xml. The attached patch contains this changes.
> > > > 
> > > > The files docs/libvirt-api.xml and docs/libvirt-refs.xml are generated
> > > > by apibuild.py, why are this generated files under version control?
> > > 
> > > Yeah, I've been running into this too.  I think we should remove those files
> > > from version control, personally.
> > 
> >   I don't care about docs/libvirt-refs.xml, but I would prefer to keep
> > docs/libvirt-api.xml in the tree for the reasons exposed during the big
> > reshuffling.
> >   The problem is that now this is systematically rebuilt on make
> > while it used to be rebuilt only on a specific "make rebuild" target
> > in doc, this was done for example on "make dist", this is why so many
> > people start to see diffs.
> 
> There's a couple of problems here
> 
> I did not intentionally change it to be re-generated everytime, but it
> is being done as a side-effect of building the HTML files. ie the
> html/index.html file which is the website page for the API, has a 
> dependancy on libvirt-api.xml, so make checks if it is up2date and if
> not regenerates the API file. 
> 
> The second issue is a bug in apibuild.py which tries to sort the 
> element in the XML file, but after calling sort() in the list, it
> then calls uniq() which messes up sorting again. So the XML file 
> ends up different everytime anyone builds it.
> 
> Even without that bug we constantly see changes which cause the
> re-generation of this file - eg when commiting new APIs like 
> Chris' migration ones people always forget to manually re-generate
> the XML file before commiting. Or when fixing typos in the libvirt.c
> function comments, etc people forget to re-generate.  This really
> says to me that we should not be storing this XML file in GIT, since
> every one of us constantly forgets to update it manually.

The third problem with it is that the python bindings require that
this file accurately reflect the public API, so if this doesn't
auto-build, people don't see the missing functions in the python
binding when doing new work. eg I completely forgot about python
binding for the data streams work until Chris happened to notice
it after libvirt-api.xml got rebuilt for him

Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|