After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 666509 - Specifying --enable-gtk-doc should not be required to build source packages
Specifying --enable-gtk-doc should not be required to build source packages
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other All
: Normal enhancement
: 1.20
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2011-12-19 12:32 UTC by Hib Eris
Modified: 2014-02-11 20:58 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
0001-Do-not-require-enable-gtk-doc-to-build-source-packag.patch (6.59 KB, patch)
2011-12-19 12:34 UTC, Hib Eris
none Details | Review
0001-Do-not-require-enable-gtk-doc-to-build-source-packag.patch (6.71 KB, patch)
2014-02-09 16:35 UTC, Hib Eris
committed Details | Review
Do not require --enable-gtk-doc to build source packages (6.72 KB, patch)
2014-02-09 16:53 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
committed Details | Review

Description Hib Eris 2011-12-19 12:32:33 UTC
Hi,

I got a bit frustrated when 'make dist' did not work for my project because I had not configured it with '--enable-gtk-doc'.

Thinking about that, I concluded that the enable/disable-gtk-doc option is not supposed to influence what goes into a source package. After all, having to always specify --enable-gtk-doc when doing a 'make dist' implies gtk-doc documentation is always included in source packages.

So, when running 'make dist', gtk-docs can be build independent of the enable-gtk-doc configure option, thus making life just a little bit easier for package release managers.

I will attach a patch to do this later.
Comment 1 Hib Eris 2011-12-19 12:34:43 UTC
Created attachment 203860 [details] [review]
0001-Do-not-require-enable-gtk-doc-to-build-source-packag.patch
Comment 2 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-08 17:02:35 UTC
what about putting this to Makefile.am

DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc

seems to be what a lot of gnome modules do:
> find . -name Makefile.am -exec grep -Hn "DISTCHECK_CONFIGURE_FLAGS" {} \; | grep enable-gtk-doc | wc -l
66
Comment 3 zbyszek 2014-02-08 18:02:34 UTC
It seems that the proposed patch is nicer than forcing work-arounds in all users of gtk-doc.
Comment 4 Hib Eris 2014-02-08 21:20:43 UTC
(In reply to comment #2)
> what about putting this to Makefile.am
> 
> DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc

Even when you put this in your Makefile.am, you still have to remember to run 

./configure --enable-gtk-doc 

When you simply run 

./configure

then running 'make dist' or 'make distcheck' will fail.


So patching this has two advantages:

1. No need for every user of gtk-doc to add a DISTCHECK_CONFIGURE_FLAGS to their Makefile.am

2. No need for specifying an extra argument to ./configure
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-08 22:50:07 UTC
But "make dist" needs gtk-doc to be enabled so that pre-generated docs are disted. How would that work in your case?
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-09 09:57:43 UTC
commit af19cf4b8447386d909aff46fb88b3ca64eab243
Author: Stefan Sauer <ensonic@users.sf.net>
Date:   Sun Feb 9 10:55:54 2014 +0100

    docs: mention DISTCHECK_CONFIGURE_FLAGS in the manual
    
    Explain how to ensure that make dist will include prebuild docs.
Comment 7 Hib Eris 2014-02-09 10:41:40 UTC
> But "make dist" needs gtk-doc to be enabled so that pre-generated docs are
> disted. How would that work in your case?

The configure switch '--enable-gtk-doc' would only influence the building of the documentation for the default make target, thus './configure && make' would not build documentation, while './configue --enable-gtk-doc' would build the documentation (just like it is now).

What I propose to change is that building the 'dist' make target would always imply building the documentation, independent of the '--enable-gtk-doc' option given to './configure'. When the documentation was not yet build in the 'make' fase, it can be build automatically in the 'make dist' fase.
Comment 8 Hib Eris 2014-02-09 11:01:41 UTC
(In reply to comment #6)
> commit af19cf4b8447386d909aff46fb88b3ca64eab243
> Author: Stefan Sauer <ensonic@users.sf.net>
> Date:   Sun Feb 9 10:55:54 2014 +0100
> 
>     docs: mention DISTCHECK_CONFIGURE_FLAGS in the manual
> 
>     Explain how to ensure that make dist will include prebuild docs.

This was already in the manual, it is now mentioned twice:


https://git.gnome.org/browse/gtk-doc/tree/help/manual/C/index.docbook#n502

https://git.gnome.org/browse/gtk-doc/tree/help/manual/C/index.docbook#n557
Comment 9 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-09 11:19:39 UTC
Reverted the extra docblob, thanks for the headsup. Could you update the patch?

CONFLICT (content): Merge conflict in gtk-doc.notmpl.make
Auto-merging gtk-doc.make
CONFLICT (content): Merge conflict in gtk-doc.make
Auto-merging gtk-doc.m4
CONFLICT (content): Merge conflict in gtk-doc.m4

What worries me is that we have to do all these extra things. Do other tools need to go through all these hoops as well? It seems that enabling --enable-gtk-doc on configure as a developer is fine and so is also setting the DISTCHECK_CONFIGURE_FLAGS. I agree that it is bad that if the developer has not set --enable-gtk-doc distcheck fails, but how likely is that. As a developer you almost always want to have this enabled, right?
Comment 10 Hib Eris 2014-02-09 16:34:13 UTC
(In reply to comment #9)
> What worries me is that we have to do all these extra things. Do other tools
> need to go through all these hoops as well? 

By fixing this in gtk-doc.m4, we fix this automatically for all projects using gtk-doc.

> It seems that enabling
> --enable-gtk-doc on configure as a developer is fine and so is also setting the
> DISTCHECK_CONFIGURE_FLAGS. 

It creates two things a project/developer that uses gtk-doc can do wrong, without any good reason. It hinders a 'works out-of-the-box' experience.

> I agree that it is bad that if the developer has not
> set --enable-gtk-doc distcheck fails, but how likely is that. As a developer
> you almost always want to have this enabled, right?

I am afraid most developers do not build documentation by default and only do this when doing a 'make dist'.
Comment 11 Hib Eris 2014-02-09 16:35:16 UTC
Created attachment 268588 [details] [review]
0001-Do-not-require-enable-gtk-doc-to-build-source-packag.patch

Rebased on current master.
Comment 12 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-09 16:53:05 UTC
The following fix has been pushed:
cf5a300 Do not require --enable-gtk-doc to build source packages
Comment 13 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-09 16:53:11 UTC
Created attachment 268589 [details] [review]
Do not require --enable-gtk-doc to build source packages

This allows packages that use GTK_DOC_CHECK to build a source
package without having to explicitly request '--enable-gtk-doc'.

Fixes bug #666509.
Comment 14 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-09 16:53:42 UTC
Pushed, lets see what happens.
Comment 15 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-11 20:03:38 UTC
pango is currently failing to build due to gtk-doc.make:270: error: HAVE_GTK_DOC does not appear in AM_CONDITIONAL

Can you please take a look?
Comment 16 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-11 20:42:40 UTC
Re comment 15, I believe it is a case of a stale m4 file.
Comment 17 Hib Eris 2014-02-11 20:58:12 UTC
I have done a fresh jhbuild of pango and it seems to work fine, so I guess it is indeed a stale m4 file. Maybe it helps to remove pango/aclocal.m4.