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 734469 - API documentation is incomplete when srcdir != builddir (out-of-tree)
API documentation is incomplete when srcdir != builddir (out-of-tree)
Status: RESOLVED OBSOLETE
Product: glib
Classification: Platform
Component: docs
2.40.x
Other Linux
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
: 757370 (view as bug list)
Depends on:
Blocks:
 
 
Reported: 2014-08-08 08:58 UTC by Simon McVittie
Modified: 2018-05-24 16:53 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Documentation: scan builddir where necessary (3.43 KB, patch)
2014-08-08 09:07 UTC, Simon McVittie
needs-work Details | Review
Doc: copy included example files (5.28 KB, patch)
2015-10-30 19:01 UTC, Xavier Claessens
none Details | Review
Doc: copy included example files (5.29 KB, patch)
2015-10-30 19:08 UTC, Xavier Claessens
none Details | Review
Doc: copy included example files (5.45 KB, patch)
2015-10-30 19:42 UTC, Xavier Claessens
committed Details | Review
Doc: Fix missing glibconfig.h when builddir!=srcdir (3.05 KB, patch)
2015-11-02 15:02 UTC, Xavier Claessens
committed Details | Review
Build gdbus-example-objectmanager-server again (1.21 KB, patch)
2015-11-02 17:24 UTC, Simon McVittie
committed Details | Review
Fix distcheck failure when building gio's doc (985 bytes, patch)
2015-11-06 18:02 UTC, Xavier Claessens
none Details | Review
build: fix a ridiculous distcheck issue (1.35 KB, patch)
2015-11-06 18:11 UTC, Allison Karlitskaya (desrt)
none Details | Review

Description Simon McVittie 2014-08-08 08:58:45 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>)
Comment 1 Simon McVittie 2014-08-08 09:07:51 UTC
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.
Comment 2 Simon McVittie 2014-08-08 09:22:35 UTC
(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?
Comment 3 Simon McVittie 2015-10-30 15:43:01 UTC
*** Bug 757370 has been marked as a duplicate of this bug. ***
Comment 4 Simon McVittie 2015-10-30 16:32:07 UTC
(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?
Comment 5 Xavier Claessens 2015-10-30 16:33:51 UTC
Review of attachment 282884 [details] [review]:

Still apply and works fine in both srcdir==buildir and srcdir!=buildir cases.
Comment 6 Xavier Claessens 2015-10-30 19:01:23 UTC
Created attachment 314516 [details] [review]
Doc: copy included example files

This fix missing files when src_dir != build_dir.
Comment 7 Xavier Claessens 2015-10-30 19:08:21 UTC
Created attachment 314518 [details] [review]
Doc: copy included example files

This fix missing files when src_dir != build_dir.
Comment 8 Simon McVittie 2015-10-30 19:22:36 UTC
Review of attachment 314518 [details] [review]:

I'm not really part of the GLib cabal, but this looks good to me.
Comment 9 Emmanuele Bassi (:ebassi) 2015-10-30 19:36:09 UTC
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.
Comment 10 Xavier Claessens 2015-10-30 19:42:09 UTC
Created attachment 314519 [details] [review]
Doc: copy included example files

This fix missing files when src_dir != build_dir.
Comment 11 Matthias Clasen 2015-11-02 12:53:04 UTC
Review of attachment 314519 [details] [review]:

Looks good to me
Comment 12 Allison Karlitskaya (desrt) 2015-11-02 13:20:58 UTC
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?
Comment 13 Matthias Clasen 2015-11-02 13:22:50 UTC
Review of attachment 282884 [details] [review]:

This looks ugly and un-auto-esque. Why not just always scan both locations ?
Comment 14 Emmanuele Bassi (:ebassi) 2015-11-02 13:23:59 UTC
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 15 Xavier Claessens 2015-11-02 14:27:39 UTC
Comment on attachment 314519 [details] [review]
Doc: copy included example files

Attachment 314519 [details] pushed as 86a7c86 - Doc: copy included example files
Comment 16 Xavier Claessens 2015-11-02 15:02:58 UTC
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.
Comment 17 Simon McVittie 2015-11-02 15:40:07 UTC
(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=
Comment 18 Matthias Clasen 2015-11-02 15:44:21 UTC
Review of attachment 314647 [details] [review]:

this looks ok to me
Comment 19 Xavier Claessens 2015-11-02 16:04:14 UTC
Thanks !
Comment 20 Simon McVittie 2015-11-02 17:24:20 UTC
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]
Comment 21 Colin Walters 2015-11-02 19:16:31 UTC
Review of attachment 314675 [details] [review]:

Oops, sorry about that.
Comment 22 Simon McVittie 2015-11-02 20:49:45 UTC
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)
Comment 23 Xavier Claessens 2015-11-06 18:02:50 UTC
Created attachment 315008 [details] [review]
Fix distcheck failure when building gio's doc
Comment 24 Xavier Claessens 2015-11-06 18:04:35 UTC
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.
Comment 25 Allison Karlitskaya (desrt) 2015-11-06 18:06:21 UTC
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...
Comment 26 Allison Karlitskaya (desrt) 2015-11-06 18:11:13 UTC
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 27 Simon McVittie 2015-11-07 09:33:24 UTC
Comment on attachment 282884 [details] [review]
Documentation: scan builddir where necessary

obsoleted by one of Xavier's patches
Comment 28 Simon McVittie 2015-11-07 09:42:38 UTC
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.
Comment 29 GNOME Infrastructure Team 2018-05-24 16:53:57 UTC
-- 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.