GNOME Bugzilla – Bug 700093
[PATCH] always generate documentation at dist time
Last modified: 2013-05-14 16:02:03 UTC
Created attachment 243803 [details] [review] 0001-build-always-generate-docs-at-dist-time.patch dist-ed tarballs should always include documentation; this was actually the case with NM due to the distcheck flags inclusion of --with-docs=yes. However, there was one major problem... The builds required --enable-doc/--with-docs=yes to even *install* the documentation, which means that packages or downstream builders could use the disted documentation without also rebuilding that documentation. Rebuilding the documentation during the build leads to a number of problems: 1) gtkdoc used to (and may still) use randomized link names, which causes conflicts between the packages built for different architectures when installed on multi-lib systems; the docs should instead be the same across all arches for the same package version 2) gtk-doc.make breaks Fedora's hardened build macros (fPIC and fPIE) due to double-definition of CFLAGS and LDFLAGS (rh bug #853199) when building the documentation; arguably a bug in gtk-doc but happily made irrelevant by this patch So this patch changes the behavior slightly: 1) deprecate all existing documentation switches 2) use the standard --enable-gtk-doc switch to turn documentation on 3) requires documentation enabled to make a dist tarball 4) allows pre-generated documentation to be installed regardless of whether downstream builds use --enable-gtk-doc or not
On the Fedora side, this allows us to stop generating documentation during the RPM build process and use the tarball pregenerated documentation, which has the side-benefit of not causing build errors when using "%global hardened_build 1".
Comment on attachment 243803 [details] [review] 0001-build-always-generate-docs-at-dist-time.patch >+# Documentation backwards compat options >+AC_ARG_ENABLE(doc, AS_HELP_STRING([--enable-doc], [Build NetworkManager documentation (deprecated)])) >+AC_ARG_WITH(docs, AS_HELP_STRING([--with-docs], [Build NetworkManager documentation (deprecated)])) do we care? configure will warn if you pass it unrecognized options... Two problems: - We now always try to build the man pages, but configure doesn't check if you have xsltproc installed. (It's a dep of gtk-doc, so if you had gtk-doc you're definitely OK, but if you don't, then maybe not.) - in doc/api/Makefile.am, the rule for spec.html is: spec.html: $(XMLS) $(OTHER_FILES) html-build.stamp but it turns out that all --disable-gtk-doc does basically is tell gtk-doc.make to not build html-build.stamp. So by pulling it in via spec.html's dependencies, you end up trying to build the docs even if you'd passed --disable-gtk-doc. I guess you need to make spec.html depend on ENABLE_GTK_DOC too.
(In reply to comment #2) > (From update of attachment 243803 [details] [review]) > >+# Documentation backwards compat options > >+AC_ARG_ENABLE(doc, AS_HELP_STRING([--enable-doc], [Build NetworkManager documentation (deprecated)])) > >+AC_ARG_WITH(docs, AS_HELP_STRING([--with-docs], [Build NetworkManager documentation (deprecated)])) > > do we care? configure will warn if you pass it unrecognized options... We probably don't. The latter one was added by me to avoid disturbing current builds. I think both of them should be removed in favor of --enable-gtk-doc/--disable-gtk-doc.
Created attachment 244187 [details] [review] 0001-build-always-generate-docs-at-dist-time.patch Removed backwards compat docs options, no longer builds manpages when --enable-gtk-doc is not passed.
Comment on attachment 244187 [details] [review] 0001-build-always-generate-docs-at-dist-time.patch looks good
Merged.