[libvirt] Update libvirt API and refs XML files

[Daniel Veillard]

On Fri, Oct 02, 2009 at 12:38:05PM +0100, Daniel P. Berrange wrote:
> 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

  Okay, I surrender ... you can remove them from git !

Daniel

-- 
Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
daniel at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/