GNOME Bugzilla – Bug 590927
Support AM_SILENT_RULES for doc-build steps
Last modified: 2011-04-14 14:41:36 UTC
It would be nice if gtk-doc supported pretty compilation output with AM_SILENT_RULES. See: http://live.gnome.org/GnomeGoals/NicerBuilds
Like other projects I'd like to wait a bit for automake 1.11 to become more widely available. Also are you requestion that gtk-doc itself build silently or that the doc build in other modules using gtk-doc should support silent rules. In any case I need to figure what I have to change ...
I was thinking about the doc build in other modules using gtk-doc; making that silent would be nice. It should just take a good sprinkling of AM_V_GEN.
Phillip, do you know a project that has custom silent rules?
Stefan, maybe this helps: http://git.gnome.org/cgit/evince/commit/?id=7b5e14ea3df691578a091c563be0081ff850a367 or http://git.gnome.org/cgit/gedit/commit/?id=1e18ae038b63dfb5889c15fb3108937dbf8aad9f (more examples in http://live.gnome.org/GnomeGoals/NicerBuilds)
That looks easy. Now the problem is that I would need to add those to gtk-doc.make, where I have no control if the project using gtk-doc.mak is using silent rules or not. So if someone has no support for silent rules $(AM_V_GEN) becomes "" and thus shows no effect, right? I'll try this later.
(In reply to comment #5) > That looks easy. Now the problem is that I would need to add those to > gtk-doc.make, where I have no control if the project using gtk-doc.mak is using > silent rules or not. So if someone has no support for silent rules $(AM_V_GEN) > becomes "" and thus shows no effect, right? I'll try this later. From http://www.gnu.org/software/hello/manual/automake/Options.html "You can use the predefined variable AM_V_GEN as a prefix to commands that should output a status line in silent mode, and AM_V_at as a prefix to commands that should not output anything in silent mode. When output is to be verbose, both of these variables will expand to the empty string."
this is the current output. I could remove/change the echo lines (gtk-doc: ...). Most of the other lines are from docbook xsl and dblatex. gtk-doc: Scanning header files gtk-doc: Compiling scanner CC buzztard-cmd-scan.o gtk-doc: Linking scanner LINK buzztard-cmd-scan gtk-doc: Running scanner buzztard-cmd-scan gtk-doc: Building XML ./buzztard-cmd-unused.txt:1: warning: 6 unused declarations.They should be added to buzztard-cmd-sections.txt in the appropriate place. gtk-doc: Building HTML Computing chunks... Writing pr01.html for preface Writing pt01.html for part Writing buzztard-cmd-btcmd.html for refentry(buzztard-cmd-btcmd) Writing BtCmdApplication.html for refentry(BtCmdApplication) Writing uibtcmd.html for reference(uibtcmd) Writing objecttree.html for chapter(objecttree) Writing api-index.html for index(api-index) Writing pt02.html for part Writing index.html for book(index) Writing index.sgml for book(index) Writing buzztard-cmd.devhelp for book(index) Writing buzztard-cmd.devhelp2 for book(index) gtk-doc: Fixing cross-references gtk-doc: Building PDF /usr/share/dblatex/lib/dbtexmf/dblatex/grubber/util.py:8: DeprecationWarning: the md5 module is deprecated; use hashlib instead import md5 Build the book set list... Build the listings... XSLT stylesheets DocBook - LaTeX 2e (0.2.11-1) =================================================== link not supported in programlisting or screen returnvalue not supported in programlisting or screen ... Build buzztard-cmd-docs.sgml.pdf This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) %&-line parsing enabled. entering extended mode processing index /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.idx... This is makeindex, version 2.14 [02-Oct-2002] (kpathsea + Thai support). Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored). Scanning input file /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.idx....done (7 entries accepted, 0 rejected). Sorting entries....done (27 comparisons). Generating output file /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.ind....done (12 lines written, 0 warnings). Output written in /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.ind. Transcript written in /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.ilg. This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) %&-line parsing enabled. entering extended mode This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) %&-line parsing enabled. entering extended mode 'buzztard-cmd.pdf' successfully built I tried to changie it localy but it would now look like: test -z "buzztard-cmd.args buzztard-cmd.hierarchy buzztard-cmd.interfaces buzztard-cmd.prerequisites buzztard-cmd.signals buzztard-cmd-undocumented.txt buzztard-cmd-undeclared.txt buzztard-cmd-unused.txt scan-build.stamp sgml-build.stamp html-build.stamp pdf-build.stamp ./sgml.stamp ./html.stamp ./pdf.stamp" || rm -f buzztard-cmd.args buzztard-cmd.hierarchy buzztard-cmd.interfaces buzztard-cmd.prerequisites buzztard-cmd.signals buzztard-cmd-undocumented.txt buzztard-cmd-undeclared.txt buzztard-cmd-unused.txt scan-build.stamp sgml-build.stamp html-build.stamp pdf-build.stamp ./sgml.stamp ./html.stamp ./pdf.stamp rm -rf .libs _libs GEN clean-local GEN clean-local rm -f *.lo GEN scan-build.stamp gtk-doc: Scanning header files GEN scan-build.stamp GEN scan-build.stamp GEN scan-build.stamp gtk-doc: Compiling scanner libtool: compile: gcc -g -O2 -I../../../src/lib/core -I../../../src/lib/ic -I../../../src/ui/cmd -I../../.. -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -I/usr/include/gstreamer-0.10 -DORBIT2=1 -pthread -I/usr/include/gconf/2 -I/usr/include/orbit-2.0 -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -pthread -I/home/ensonic/buzztard/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/gstreamer-0.10 -I/home/ensonic/buzztard/include -DDBUS_API_SUBJECT_TO_CHANGE -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/hal -I/usr/include/libgsf-1 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -O0 -Wall -Werror -g -g -O2 -c buzztard-cmd-scan.c -fPIC -DPIC -o .libs/buzztard-cmd-scan.o libtool: compile: gcc -g -O2 -I../../../src/lib/core -I../../../src/lib/ic -I../../../src/ui/cmd -I../../.. -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -I/usr/include/gstreamer-0.10 -DORBIT2=1 -pthread -I/usr/include/gconf/2 -I/usr/include/orbit-2.0 -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -pthread -I/home/ensonic/buzztard/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/gstreamer-0.10 -I/home/ensonic/buzztard/include -DDBUS_API_SUBJECT_TO_CHANGE -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/hal -I/usr/include/libgsf-1 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -O0 -Wall -Werror -g -g -O2 -c buzztard-cmd-scan.c -o buzztard-cmd-scan.o >/dev/null 2>&1 gtk-doc: Linking scanner libtool: link: gcc -g -O2 -o .libs/buzztard-cmd-scan .libs/buzztard-cmd-scan.o -pthread -Wl,--export-dynamic -pthread -Wl,--export-dynamic -Wl,--warn-common ../../../src/lib/core/.libs/libbuzztard-core.so ../../../src/lib/ic/.libs/libbuzztard-ic.so ../../../src/ui/cmd/.libs/libbtcmd.a /usr/lib/libgstcontroller-0.10.so /usr/lib/libgstbase-0.10.so /usr/lib/libgconf-2.so -L/home/ensonic/buzztard/lib /home/ensonic/buzztard/lib/libgstbuzztard.so /usr/lib/libgstreamer-0.10.so /usr/lib/libgmodule-2.0.so /usr/lib/libgthread-2.0.so /home/ensonic/buzztard/lib/libbml.so -L/lib -ldbus-glib-1 -lhal -ldbus-1 -lpthread -lgsf-1 /usr/lib/libgobject-2.0.so /usr/lib/libxml2.so /usr/lib/libglib-2.0.so -lrt -pthread -Wl,-rpath -Wl,/home/ensonic/buzztard/lib gtk-doc: Running scanner buzztard-cmd-scan GEN scan-build.stamp GEN sgml-build.stamp gtk-doc: Building XML GEN sgml-build.stamp GEN sgml-build.stamp ./buzztard-cmd-unused.txt:1: warning: 6 unused declarations.They should be added to buzztard-cmd-sections.txt in the appropriate place. GEN sgml-build.stamp GEN html-build.stamp gtk-doc: Building HTML GEN html-build.stamp GEN html-build.stamp GEN html-build.stamp GEN html-build.stamp Computing chunks... Writing pr01.html for preface Writing pt01.html for part Writing buzztard-cmd-btcmd.html for refentry(buzztard-cmd-btcmd) Writing BtCmdApplication.html for refentry(BtCmdApplication) Writing uibtcmd.html for reference(uibtcmd) Writing objecttree.html for chapter(objecttree) Writing api-index.html for index(api-index) Writing pt02.html for part Writing index.html for book(index) Writing index.sgml for book(index) Writing buzztard-cmd.devhelp for book(index) Writing buzztard-cmd.devhelp2 for book(index) GEN html-build.stamp GEN html-build.stamp gtk-doc: Fixing cross-references GEN html-build.stamp GEN html-build.stamp GEN pdf-build.stamp gtk-doc: Building PDF GEN pdf-build.stamp GEN pdf-build.stamp GEN pdf-build.stamp /usr/share/dblatex/lib/dbtexmf/dblatex/grubber/util.py:8: DeprecationWarning: the md5 module is deprecated; use hashlib instead import md5 Build the book set list... Build the listings... XSLT stylesheets DocBook - LaTeX 2e (0.2.11-1) =================================================== link not supported in programlisting or screen returnvalue not supported in programlisting or screen parameter not supported in programlisting or screen ... Build buzztard-cmd-docs.sgml.pdf This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) %&-line parsing enabled. entering extended mode processing index /tmp/tmpjErovr/buzztard-cmd-docs.sgml.idx... This is makeindex, version 2.14 [02-Oct-2002] (kpathsea + Thai support). Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored). Scanning input file /tmp/tmpjErovr/buzztard-cmd-docs.sgml.idx....done (7 entries accepted, 0 rejected). Sorting entries....done (27 comparisons). Generating output file /tmp/tmpjErovr/buzztard-cmd-docs.sgml.ind....done (12 lines written, 0 warnings). Output written in /tmp/tmpjErovr/buzztard-cmd-docs.sgml.ind. Transcript written in /tmp/tmpjErovr/buzztard-cmd-docs.sgml.ilg. This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) %&-line parsing enabled. entering extended mode This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) %&-line parsing enabled. entering extended mode 'buzztard-cmd.pdf' successfully built GEN pdf-build.stamp
Ideally that compilation would output something like the following (though I'm not sure whether all of them should use "DOC" rather than something like "HTML" or "PDF"): DOC Scanning header files CC buzztard-cmd-scan.o LINK buzztard-cmd-scan DOC Running scanner buzztard-cmd-scan DOC Building XML ./buzztard-cmd-unused.txt:1: warning: 6 unused declarations.They should be added to buzztard-cmd-sections.txt in the appropriate place. DOC Building HTML DOC pr01.html for preface DOC pt01.html for part DOC buzztard-cmd-btcmd.html for refentry(buzztard-cmd-btcmd) DOC BtCmdApplication.html for refentry(BtCmdApplication) DOC uibtcmd.html for reference(uibtcmd) DOC objecttree.html for chapter(objecttree) DOC api-index.html for index(api-index) DOC pt02.html for part DOC index.html for book(index) DOC index.sgml for book(index) DOC buzztard-cmd.devhelp for book(index) DOC buzztard-cmd.devhelp2 for book(index) DOC Fixing cross-references DOC Building PDF You can create a custom "DOC" rule with the following code: V_DOC = $(V_DOC_$(V)) V_DOC_ = $(V_DOC_$(AM_DEFAULT_VERBOSITY)) V_DOC_0 = echo " DOC " $@;
Stefan: any news about this? It would be great to have this for 1.16 ;)
I still totally fail to understand how I am supposed to apply the tips from the links: Obviously I can change some echo. But then make[3]: Betrete Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl' DOC 12:09:07.660039263: Scanning header files DOC 12:09:07.721268464: Introspecting gobjects gtk-doc: Compiling scanner libtool: compile: gcc -g -O2 -Wall -I../../../tests/gobject/src -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -g -O2 -Wall -c tester-scan.c -fPIC -DPIC -o .libs/tester-scan.o libtool: compile: gcc -g -O2 -Wall -I../../../tests/gobject/src -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -g -O2 -Wall -c tester-scan.c -o tester-scan.o >/dev/null 2>&1 gtk-doc: Linking scanner libtool: link: gcc -g -O2 -Wall .libs/tester-scan.o -pthread -o tester-scan /usr/lib/libgobject-2.0.so /usr/lib/libgthread-2.0.so -lrt /usr/lib/libglib-2.0.so ../../../tests/gobject/src/.libs/libtester.a -pthread gtk-doc: Running scanner tester-scan The lines between "gtk-doc: Compiling scanner" and "gtk-doc: Running scanner tester-scan" come from gtkdoc-scangobj, how can any V_DOC or AM_GEN affect printf statements inside this tool. Further V_DOC_0 = echo " DOC " $@; does not make sense imho, as it would print stuff like: DOC xxx-build.stamp which is not meaningful to the user. In the html step, the output like: Computing chunks... Writing intro.html for preface(intro) Writing Overview-building.html for chapter(Overview-building) comes from the docbook stylesheets. Are you sugestting that I pass $(AM_DEFAULT_VERBOSITY) to the gtk-doc tools and try to use sed scripts to mange the output of the tools I am calling?
This is how it looks right now (intentionally with some warnings): - need to check the remaining messages from the html docbook stylesheets - wrote an email to dblatex devel to see if we can trim the output there make[2]: Betrete Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl' DOC Scanning header files DOC Introspecting gobjects DOC Rebuilding template files DOC Building XML DOC Building HTML ../xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined <refsect2 id="GtkdocEnum" role="enum"> ^ Computing chunks... Warning: multiple "IDs" for constraint linkend: GtkdocEnum. Warning: multiple "IDs" for constraint linkend: GtkdocEnum. Warning: multiple "IDs" for constraint linkend: GtkdocEnum. Warning: multiple "IDs" for constraint linkend: GtkdocEnum. Warning: multiple "IDs" for constraint linkend: GtkdocEnum. Writing index.sgml for book(index) Writing tester.devhelp for book(index) Writing tester.devhelp2 for book(index) DOC Fixing cross-references DOC Building PDF /usr/share/dblatex/lib/dbtexmf/dblatex/grubber/util.py:8: DeprecationWarning: the md5 module is deprecated; use hashlib instead import md5 Build the book set list... /home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl/xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined <refsect2 id="GtkdocEnum" role="enum"> ^ Build the listings... /home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl/xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined <refsect2 id="GtkdocEnum" role="enum"> ^ /home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl/xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined <refsect2 id="GtkdocEnum" role="enum"> ^ XSLT stylesheets DocBook - LaTeX 2e (0.3-1) =================================================== Build tester-docs.pdf processing index /tmp/tmpgIolyY/tester-docs.idx... This is makeindex, version 2.15 [TeX Live 2009] (kpathsea + Thai support). Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored). Scanning input file /tmp/tmpgIolyY/tester-docs.idx....done (26 entries accepted, 0 rejected). Sorting entries....done (124 comparisons). Generating output file /tmp/tmpgIolyY/tester-docs.ind....done (30 lines written, 0 warnings). Output written in /tmp/tmpgIolyY/tester-docs.ind. Transcript written in /tmp/tmpgIolyY/tester-docs.ilg. make[2]: Verlasse Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl'
(In reply to comment #11) > This is how it looks right now (intentionally with some warnings): > - need to check the remaining messages from the html docbook stylesheets > - wrote an email to dblatex devel to see if we can trim the output there That looks like a good start. I believe the usual tactic for dealing with programs like dblatex is to (iff silent mode is enabled) either: 1. pass a --silent option to the program, or 2. pipe the program's output to /dev/null. From a quick look at dblatex's man page, it doesn't seem to have a --silent option, so I guess the best we could do at the moment would be to pipe its stdout to /dev/null iff silent mode is enabled. Obviously, if the verbosity was increased (e.g. make was called with V=1), the output of dblatex shouldn't be piped to /dev/null. Makefile.introspection has a decent example of conditionally passing options to programs depending on the verbosity level, and it shouldn't be hard to extend this to conditionally piping output: http://git.gnome.org/browse/gobject-introspection/tree/Makefile.introspection#n66
This it the mail to dblatex-devel for reference: http://sourceforge.net/mailarchive/forum.php?thread_name=4DA5A43F.5030305%40hora-obscura.de&forum_name=dblatex-devel I am already redirecting stdout to >/dev/null for silent mode: http://git.gnome.org/browse/gtk-doc/tree/gtkdoc-mkpdf.in#n99 Unfortunately that does not work, if the tool in question exec other tools with new file-descriptors. Thanks got the link, I'll see if I can find something nice in there.
make[2]: Betrete Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs' DOC Scanning header files DOC Introspecting gobjects DOC Building XML DOC Building HTML DOC Fixing cross-references DOC Building PDF XSLT stylesheets DocBook - LaTeX 2e (0.3-1) =================================================== This is makeindex, version 2.15 [TeX Live 2009] (kpathsea + Thai support). Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored). Scanning input file /tmp/tmpSbqKOH/tester-docs.idx....done (26 entries accepted, 0 rejected). Sorting entries....done (124 comparisons). Generating output file /tmp/tmpSbqKOH/tester-docs.ind....done (30 lines written, 0 warnings). Output written in /tmp/tmpSbqKOH/tester-docs.ind. Transcript written in /tmp/tmpSbqKOH/tester-docs.ilg. make[2]: Verlasse Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs' This is with two patches for dblatex (submitted upstream). Two more patches and the remaining spam should be gone. I will declare this bug as closed already.