[Bug 762707] New: common: generate documentation without any introspection files checked in srcdir

[GStreamer (GNOME Bugzilla)]

https://bugzilla.gnome.org/show_bug.cgi?id=762707

            Bug ID: 762707
           Summary: common: generate documentation without any
                    introspection files checked in srcdir
    Classification: Platform
           Product: GStreamer
           Version: git master
                OS: All
            Status: NEW
          Severity: normal
          Priority: Normal
         Component: common
          Assignee: gstreamer-bugs at lists.freedesktop.org
          Reporter: sebras at hotmail.com
        QA Contact: gstreamer-bugs at lists.freedesktop.org
     GNOME version: ---

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.

-- 
You are receiving this mail because:
You are the QA Contact for the bug.
You are the assignee for the bug.