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 762707 - common: generate documentation without any introspection files checked in srcdir
common: generate documentation without any introspection files checked in srcdir
Status: RESOLVED FIXED
Product: GStreamer
Classification: Platform
Component: common
git master
Other All
: Normal normal
: 1.7.90
Assigned To: GStreamer Maintainers
GStreamer Maintainers
Depends on:
Blocks:
 
 
Reported: 2016-02-26 01:44 UTC by Sebastian Rasmussen
Modified: 2016-02-26 07:26 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Proposed patch. (1004 bytes, patch)
2016-02-26 01:45 UTC, Sebastian Rasmussen
committed Details | Review

Description Sebastian Rasmussen 2016-02-26 01:44:54 UTC
If no introspection files are checked into your plugin then using common/gtk-doc-plugins.mak to generate documentation will fail with:

for a in /tmp/gstreamer/gst-plugins-test/gst-plugins-test/docs/plugins/inspect/*.xml; do \
    xsltproc --stringparam module gst-plugins-test \
        /tmp/gstreamer/gst-plugins-test/gst-plugins-test/common/plugins.xsl $a > xml/`basename $a`; done
warning: failed to load external entity "/tmp/gstreamer/gst-plugins-test/gst-plugins-test/docs/plugins/inspect/*.xml"
unable to parse /tmp/gstreamer/gst-plugins-test/gst-plugins-test/docs/plugins/inspect/*.xml
Makefile:774: recipe for target 'sgml-build.stamp' failed
make[3]: *** [sgml-build.stamp] Error 6

The reason is that in common/gtk-doc-plugins.mak for loop mentioned above looks like this:

        for a in $(srcdir)/$(INSPECT_DIR)/*.xml; do \

Now, if you haven't checked in any introspect files then $(srcdir)/$(INSPECT_DIR) may not even exist or at least contains no files! This means that the wildcards above actually expand to the literal string *.xml with some preceeding directory components. So there is only one iteration in the loop and the resulting arguments given to xsltproc doesn't evaluate to anything it can load.

This is normally not a problem for gst-plugins-good or -bad or so because you guys generally check in your introspection files. This since slomo mentioned that you want to be able to generate documentation both for the architecture you are building on and, crucially, for _other_ architectures which means that introspection is not possible for all types, yet you want to generate documentation for _everything_.

So what to do? Well it turns out that someone discovered this issue for the make target check-inspected-versions in common/gtk-doc-plugins.mak as this rule depends not on a hardcoded glob pattern, but rather on the make variable $(inspect_files) which is resolved like this:

# wildcard is apparently not portable to other makes, hence the use of find
inspect_files = $(shell find $(srcdir)/$(INSPECT_DIR) -name '*.xml')

If the same variable was used in the for-loop preceeding the xsltproc command: 

        for a in $(inspect_files); do \

then it would basically evaluate to:

        for a in ; do \

which wouldn't cause any iterations of the loop at all, which means that xsltproc doesn't run at all and hence cause no problems.

The attached patch fixed my problem in this manner.
Comment 1 Sebastian Rasmussen 2016-02-26 01:45:39 UTC
Created attachment 322432 [details] [review]
Proposed patch.
Comment 2 Sebastian Dröge (slomo) 2016-02-26 07:26:17 UTC
commit 9adccfd575a412d275d901080ace644c2d14043f
Author: Sebastian Rasmussen <sebras@gmail.com>
Date:   Fri Feb 26 02:32:11 2016 +0100

    gtk-doc: Skip running xsltproc if no inspect files exist
    
    Fixes https://bugzilla.gnome.org/show_bug.cgi?id=762707