[Libguestfs] [PATCH 15/16] gobject: Improve the structure of guestfs-sections.txt

Richard W.M. Jones rjones at redhat.com
Tue Mar 27 16:20:10 UTC 2012


On Tue, Mar 27, 2012 at 04:59:48PM +0100, Matthew Booth wrote:
> On 03/27/2012 04:20 PM, Richard W.M. Jones wrote:
> >On Tue, Mar 27, 2012 at 04:00:57PM +0100, Matthew Booth wrote:
> >>The generator doesn't make a very good job of guestfs-sections.txt. This change
> >>manually fixes its title, and moves various sections which shouldn't be in the
> >>documentation into a Private subsection.
> >>
> >>This change requires removing the --rebuild-sections command line option from
> >>gtkdoc-scan. This means that any future apis will have to be manually added to
> >>guestfs-sections.txt if they are to appear in the gtk-doc output.
> >
> >Sorry, but no.  I took a strong stance against *any* manually hackery
> >and over time that stance has proven to be a good one.  Imagine we'd
> >done this with other bindings -- that would by now have negated all
> >the good work we did with the generator.
> >
> >Please explain why the generator cannot get this right, but a human can.
> >Is there some missing information we need in the generator?
> 
> Firstly, 'generator' in this context is the gtk-doc generator, not
> the libguestfs generator. The fundamental issue seems to be that it
> doesn't correctly handle more than 1 class per source file. This
> patch is, frankly, a fudge. However, it makes the output somewhat
> bearable. The correct fix for this is to split guestfs-gobject.c
> into multiple source files. This is certainly possible, but a load
> of donkey work I wanted to leave for another day.

I don't think this is such a lot of work.  Is it one per method, one
per class, (some other)?

Java requires separate files for each class, where libguestfs structs
are mapped to classes, thus each requires a separate file.  It's not
onerous at all to generate these + the associate Makefile machinery:

https://github.com/libguestfs/libguestfs/blob/e8ef35df267de6fd6308d0c49a6bdef41113cf19/generator/generator_main.ml#L121
https://github.com/libguestfs/libguestfs/blob/e8ef35df267de6fd6308d0c49a6bdef41113cf19/generator/generator_java.ml#L754

> The manual hackery required here is not onerous, and the build
> system makes it extremely simple to both notice and fix. I deleted 3
> entries from guestfs-sections.txt at random and ran make in
> gobject/docs. The output was:
> 
>   DOC   Scanning header files
>   DOC   Introspecting gobjects
>   DOC   Rebuilding template files
> ./guestfs-unused.txt:1: warning: 3 unused declarations.They should
> be added to guestfs-sections.txt in the appropriate place.
>   DOC   Building XML
> ./guestfs-unused.txt:1: warning: 3 unused declarations.They should
> be added to guestfs-sections.txt in the appropriate place.
>   DOC   Building HTML
> 
> The contents of guestfs-unused.txt is:
> guestfs_session_equal
> guestfs_session_get_pid
> guestfs_session_inotify_close
> 
> which are the 3 apis I deleted. All that's required to fix this is
> to copy those 3 entries into the api list in guestfs-sections.txt.
> 
> So I agree it's not ideal, but its a not-too-onerous, pragmatic,
> temporary workaround.

My argument is the same ... what if we'd done this for all the other
bindings?  It would negate the benefit of the generator.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine.  Supports Linux and Windows.
http://et.redhat.com/~rjones/virt-df/




More information about the Libguestfs mailing list