[cairo] Rethinking cairo's build system

[Behdad Esfahbod]

On Fri, 2006-06-30 at 08:41 -0400, Damon Chaplin wrote:
> On Sat, 2006-06-24 at 19:53 +0200, Carl Worth wrote:
> > On Sat, 24 Jun 2006 18:43:16 +0100, Damon Chaplin wrote:
> > > > 
> > > > 4) Building the docs takes too long, (or perhaps it just needs to be
> > > >    moved to "make doc" instead of "make)
> > > 
> > > Or you can use './configure --disable-gtk-doc' to skip building the
> > > documentation.
> > 
> > But configure is slow, so I wouldn't want to have to go through it
> > again (twice!) just to be able to build the docs and then turn them
> > off again. So a separate make target is definitely what I want here.
> 
> OK. I've added a separate 'docs' target you can use in the documentation
> directory, even if '--disable-gtk-doc' has been used.

Thanks Damon.  Before getting your mail, I went on and hacked cairo's
gtk-doc.make locally to add a 'doc' target that does about the same.
Will switch to gtkdocize and your new feature.

So, you are changing gtk-doc to not build docs by default anymore?  That
makes many people happy I'm sure.  But looking at your implementation
versus mine, I've made both dist-hook and install-data-local to depend
on html-build.stamp, but you only do for dist-hook.  I think someone
enabling gtk-doc should get updated docs installed.  This has caused a
minor glitch for cworth though: sudo make install leaves root-owned
files in the tree.


> > > > 6) Building the docs modifies (!) a bunch of files under version
> > > >    control. This is worse than annoying.
> > > 
> > > It updates the template files, but should only do that if needed.
> > > Is it updating anything else under version control?
> > 
> > It's just template files that I've seen. But there a couple problems
> > here:
> > 
> > 	1) It generates output with trailing whitespace
> 
> Why is trailing whitespace a problem?

Cause we've opted for the git commit hook that fails on committing text
with trailing whitespace.  That's to help with "improved source
quality" :-).


> > 	2) Different versions of gtk-doc generate different template
> >            results, (and often in fairly trivial ways, which makes the
> >            change all the more annoying when they're under version
> >            control).
> 
> Yes, unfortunately 2 minor bugs in the handling of template files turned
> up recently, and the fixes tried to clean up the old errors, resulting
> in minor changes.
> 
> If people use a recent gtk-doc that would help here (cvs would be best).

Can you make a release?


> It also helps if people only commit docs if they have worked on them.

True, but it gets in the way, making git diff (or cvs diff, for that
matter) less usable, and one has got to keep in mind to not commit the
entire tree.


> > > It is now possible to write all the gtk-doc documentation in the source
> > > code, and not place the template files under version control. That might
> > > help you a bit. (goocanvas does that.) If you want help with that, let
> > > me know. (You just need to add an empty tmpl/dummy.sgml file to avoid
> > > issues with make.)
> > 
> > That sounds like the perfect thing. And I would love help with that.
> 
> I've converted the existing section documentation to the inline versions
> and attached it. You just need to place each part in the corresponding
> file. (Or you could just put them in one .c file.)

Thanks!  Going to commit it soonish.  However, cworth and I couldn't
quite figure out how this works, looking at goocanvas.  Does it scan
source files for inline versions only if no template file is available?
Cause we converted just one section into inline comments and gtk-doc
didn't pick it up.


> You can then remove all the tmpl/*.sgml files from version control
> (so long as there is no other documentation in the tmpl/* files.)
> But place a special tmpl/dummy.sgml file there to avoid a problem with
> make and globs.
> 
> But you'll need gtk-doc from cvs to build the docs, as I just fixed
> another bug with inline section docs.

Ok, then we really need a release before going on and do that, or, is
the bug minor enough to ignore?


> Damon

Thanks.

-- 
behdad
http://behdad.org/

"Commandment Three says Do Not Kill, Amendment Two says Blood Will Spill"
        -- Dan Bern, "New American Language"