GNOME Bugzilla – Bug 734469
API documentation is incomplete when srcdir != builddir (out-of-tree)
Last modified: 2018-05-24 16:53:57 UTC
When GLib is built with srcdir != builddir, the API documentation is incomplete: * the contents of generated headers such as glibconfig.h are not scanned, so e.g. gintptr is entirely undocumented * the various places that still XInclude source code as examples (as opposed to using an external link) get an XInclude error because the xi:include appears in XML in the builddir, so it is interpreted relative to the builddir, not the srcdir (This is <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=659977>)
Created attachment 282884 [details] [review] Documentation: scan builddir where necessary Previously, the contents of glibconfig.h and other generated headers were not scanned in srcdir != builddir builds, leading to things like gintptr and G_GOFFSET_MODIFIER being undocumented.
(In reply to comment #0) > * the various places that still XInclude source code as examples > (as opposed to using an external link) get an XInclude error > because the xi:include appears in XML in the builddir, so it is > interpreted relative to the builddir, not the srcdir This is much less visible in 2.40 and master than it was when the Debian bug was filed. docs/reference/gio/migrating-gdbus.xml fails to XInclude three files: ../../../../gio/tests/gdbus-object-manager-example/gdbus-example-objectmanager.xml ../../../../gio/tests/gdbus-example-objectmanager-server.c ../../../../gio/tests/gdbus-example-objectmanager-client.c The easiest way to resolve this is probably for the build to just copy those files from $(top_srcdir)/gio/tests/ into either $(top_builddir)/gio/tests/ or $(top_builddir)/docs/reference/gio/xml/. Any preference?
*** Bug 757370 has been marked as a duplicate of this bug. ***
(In reply to Simon McVittie from comment #1) > Documentation: scan builddir where necessary This still applies, and seems to work. It won't fix the remaining uses of XInclude, but it solves half the problem. May I apply it?
Review of attachment 282884 [details] [review]: Still apply and works fine in both srcdir==buildir and srcdir!=buildir cases.
Created attachment 314516 [details] [review] Doc: copy included example files This fix missing files when src_dir != build_dir.
Created attachment 314518 [details] [review] Doc: copy included example files This fix missing files when src_dir != build_dir.
Review of attachment 314518 [details] [review]: I'm not really part of the GLib cabal, but this looks good to me.
Review of attachment 314518 [details] [review]: ::: docs/reference/gio/Makefile.am @@ +152,3 @@ +$(example_files): + cp $< $@ + Shouldn't $(example_files) be added to CLEANFILES as well? Otherwise they'll stick around and distcheck will likely fail.
Created attachment 314519 [details] [review] Doc: copy included example files This fix missing files when src_dir != build_dir.
Review of attachment 314519 [details] [review]: Looks good to me
Review of attachment 282884 [details] [review]: The commit message doesn't say anything about what you're doing to fix this. ::: docs/reference/glib/Makefile.am @@ +26,3 @@ HFILE_GLOB=$(top_srcdir)/glib/*.h $(top_srcdir)/gmodule/*.h +if !SRCDIR_EQ_BUILDDIR +HFILE_GLOB += $(top_builddir)/glib/*.h $(top_builddir)/gmodule/*.h Can you just list the explicit files here?
Review of attachment 282884 [details] [review]: This looks ugly and un-auto-esque. Why not just always scan both locations ?
I don't understand why you need to SRCDIR_EQ_BUILDDIR hack at all. Can't you just glob $(top_builddir) unconditionally? I assume gtk-doc is not going to go through the files twice if they have the exact same path (read: I already do this in the modules I maintain, and have not seen any issue with it).
Comment on attachment 314519 [details] [review] Doc: copy included example files Attachment 314519 [details] pushed as 86a7c86 - Doc: copy included example files
Created attachment 314647 [details] [review] Doc: Fix missing glibconfig.h when builddir!=srcdir Currently the doc is incomplete when builddir!=srcdir (e.g. debian package) because glibconfig.h is generared from configure.ac and is thus missing from srcdir. This leads to missing doc for symbols like G_GINT64_FORMAT.
(In reply to Emmanuele Bassi (:ebassi) from comment #14) > I don't understand why you need to SRCDIR_EQ_BUILDDIR hack at all. Can't you > just glob $(top_builddir) unconditionally? Yes if you're happy to rely on gtk-doc's current behaviour as essentially being API. > I assume gtk-doc is not going to > go through the files twice if they have the exact same path For DOC_SOURCE_DIR, according to its source code, # do not read files twice; checking it here permits to give both srcdir and # builddir as --source-dir without fear of duplicities so it looks as though that's, if not exactly documented, then at least deliberate. For the globs, scan-build.stamp depends on $(HFILE_GLOB) $(CFILE_GLOB), so duplicates have no practical effect. The only documentation for these variables seems to be the comments in the example Makefile.am, which doesn't make any mention of what would happen if ${srcdir} and ${builddir} differ, or if they contain duplicates: # Directories containing the source code. # gtk-doc will search all .c and .h files beneath these paths # for inline comments documenting functions and macros. # e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk DOC_SOURCE_DIR= # Used for dependencies. The docs will be rebuilt if any of these change. # e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h # e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c HFILE_GLOB= CFILE_GLOB=
Review of attachment 314647 [details] [review]: this looks ok to me
Thanks !
Created attachment 314675 [details] [review] Build gdbus-example-objectmanager-server again It was removed, apparently accidentally, in commit 5b48dc4. This had the side-effect that it wasn't included in tarball releases, which means that commit ab7b4be doesn't work when building a package. --- ab7b4be = Attachment #314519 [details]
Review of attachment 314675 [details] [review]: Oops, sorry about that.
Comment on attachment 314675 [details] [review] Build gdbus-example-objectmanager-server again Committed 9fa97b3 glib-2-46 (for 2.46.2) 236e804 master (for 2.47.2)
Created attachment 315008 [details] [review] Fix distcheck failure when building gio's doc
I don't understand why those files already exists in the destination location when doing distcheck, but they are read-only so 'cp' command fails to override them. This is a workaround, but I don't know autotools enough to understand the root cause.
I think I just realised the problem. The file is probably readonly because it was copied from the readonly srcdir earlier and the for some reason, we try to copy it again...
Created attachment 315009 [details] [review] build: fix a ridiculous distcheck issue I prefer this solution because it means that we don't end up with read-only files in builddir (nor are we trying to delete a file which isn't there to begin with).
Comment on attachment 282884 [details] [review] Documentation: scan builddir where necessary obsoleted by one of Xavier's patches
Review of attachment 315009 [details] [review]: ::: docs/reference/gio/Makefile.am @@ +142,3 @@ gdbus-example-objectmanager-generated-org.gtk.GDBus.Example.ObjectManager.Cat.xml: %: $(top_builddir)/gio/tests/gdbus-object-manager-example/% $(example_files): + dd if=$< of=$@ dd seems like the wrong tool for general file-copying, and also seems like the sort of thing that might be missing on niche platforms. "cat < $< > $@" (closer to this patch), or "cp -f" (closer to Xavier's)? cp and cat are ubiquitous, and cp -f is in POSIX, so it's probably safe-ish.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/glib/issues/912.