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 156643 - Avoid make error in gtk-doc.make
Avoid make error in gtk-doc.make
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other All
: Normal normal
: 1.9
Assigned To: gtk-doc maintainers
gtk-doc maintainers
: 452461 (view as bug list)
Depends on:
Blocks:
 
 
Reported: 2004-10-27 21:45 UTC by Simon Josefsson
Modified: 2007-09-22 19:09 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
my conclusion of the bugreport (716 bytes, patch)
2005-08-24 20:41 UTC, Geert Stappers
rejected Details | Review

Description Simon Josefsson 2004-10-27 21:45:43 UTC
I don't have any files in CVS inside tmpl/, so I get a warning during make (see
below).  It is slightly surprising, because after make dies, there are
tmpl/'.sgml files.  I suspect make tests for the files too early.  This patch
let make know about the dependency better:

--- gtk-doc.make	24 Oct 2004 17:11:01 +0200	1.9
+++ gtk-doc.make	27 Oct 2004 23:44:02 +0200	
@@ -66,7 +66,7 @@
 
 #### templates ####
 
-tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES)
$(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
+tmpl-build.stamp tmpl/*.sgml: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES)
$(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
 	@echo '*** Rebuilding template files ***'
 	@-chmod -R u+w $(srcdir)
 	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)


jas@latte:~/src/gnutls/doc/reference$ make
*** Scanning header files ***
if grep -l '^..*$' ./gnutls.types > /dev/null ; then \
    CC="gcc   -D_REENTRANT -D_THREAD_SAFE -g -Wno-format-y2k -Wall -Wcast-align
-W -Wpointer-arith -Wchar-subscripts -Wformat-security -Wmissing-braces -Winline
-Wstrict-prototypes -pipe -I/usr/local/include  -I/usr/local/include" LD="gcc 
-D_REENTRANT -D_THREAD_SAFE -g -Wno-format-y2k -Wall -Wcast-align -W
-Wpointer-arith -Wchar-subscripts -Wformat-security -Wmissing-braces -Winline
-Wstrict-prototypes -pipe -I/usr/local/include  -I/usr/local/include " CFLAGS=""
LDFLAGS="" gtkdoc-scangobj  --module=gnutls --output-dir=. ; \
else \
    cd . ; \
    for i in gnutls.args gnutls.hierarchy gnutls.interfaces gnutls.prerequisites
gnutls.signals ; do \
               test -f $i || touch $i ; \
    done \
fi
cd . && \
  gtkdoc-scan --module=gnutls --source-dir=../../lib --ignore-headers="debug.h
gnutls_compress.h defines.h gnutls_cipher.h gnutls_buffers.h gnutls_errors.h
gnutls_int.h gnutls_handshake.h gnutls_num.h gnutls_algorithms.h gnutls_dh.h
gnutls_kx.h gnutls_hash_int.h gnutls_cipher_int.h gnutls_db.h
gnutls_compress_int.h gnutls_session.h gnutls_priority.h gnutls_auth.h
auth_anon.h gnutls_extensions.h gnutls_buffer.h gnutls_auth_int.h
gnutls_random.h x509_b64.h gnutls_v2_compat.h gnutls_errors_int.h gnutls_datum.h
auth_cert.h gnutls_mpi.h gnutls_pk.h gnutls_record.h gnutls_cert.h
gnutls_constate.h gnutls_global.h strfile.h gnutls_sig.h gnutls_mem.h
gnutls_ui.h io_debug.h ext_max_record.h gnutls_session_pack.h gnutls_alert.h
gnutls_str.h gnutls_state.h gnutls_x509.h ext_cert_type.h gnutls_rsa_export.h
ext_server_name.h auth_dh_common.h ext_srp.h gnutls_srp.h auth_srp.h
auth_srp_passwd.h memmem.h der.h errors.h gstr.h parser_aux.h element.h
errors_int.h int.h mem.h structure.h common.h crq.h dsa.h mpi.h pkcs7.h
rfc2818.h verify.h compat.h dn.h extensions.h privkey.h sign.h gnutls_extra.h
lzoconf.h minilzo.h openssl_compat.h cipher.h context.h filters.h main.h md.h
packet.h stream.h types.h gnutls_openpgp.h" --source-dir ../../includes/gnutls
--source-dir ../../libextra
touch scan-build.stamp
*** Rebuilding template files ***
cd . && gtkdoc-mktmpl --module=gnutls
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
WARNING: Couldn't parse struct field: :1
###Can't parse args for function cdk_data_transform: enum cdk_crypto_mode_t
mode,cdk_strlist_t locusr, cdk_strlist_t remusr,const void * inbuf, size_t
insize,unsigned char ** outbuf, size_t * outsize,int modval

###Can't parse args for function cdk_keygen_set_prefs: enum cdk_pref_type_t
type,const unsigned char * array, size_t n

###Can't parse args for function cdk_keygen_set_algo_info: enum cdk_pk_algo_t
algo, int bits

touch tmpl-build.stamp
make: *** No rule to make target `tmpl/*.sgml', needed by `sgml-build.stamp'.  Stop.
jas@latte:~/src/gnutls/doc/reference$ ls tmpl
extra.sgml          libtasn1.sgml  openpgp.sgml.bak  pkcs12.sgml.bak
gnutls.sgml         opencdk.sgml   openssl.sgml      x509.sgml
gnutls-unused.sgml  openpgp.sgml   pkcs12.sgml       x509.sgml.bak
jas@latte:~/src/gnutls/doc/reference$
Comment 1 Damon Chaplin 2004-10-28 16:44:58 UTC
I'm not sure your patch looks right.
What will happen when the user tries to build the tmpl files for the first time?
Won't it just complain that they don't exist and stop? i.e. so you can never
build them.

The final error message always happens when building the tmpl files for the
first time. doc/setting-up.txt mentions it. If you run 'make' again it will
continue OK.
Comment 2 Simon Josefsson 2004-10-29 14:58:07 UTC
I'm not sure either the patch is correct, so I apprecate the review.

However, I can confirm that with the patch, it works when there are no *.tmpl
files.  That was the problem I had!  I have no *.tmpl files, and got the error.
 With the patch, it will silently generate the files and use them the first time.

I'm trying to avoid putting *.tmpl in CVS (they are generated files, from my
point of view), so the "final error" is the problem I have.  The current
situation require people that build from CVS (such as nightly builds..) to do
'make;make' to build GnuTLS.
Comment 3 Damon Chaplin 2004-10-31 14:31:28 UTC
Ah, I misread your patch. I thought you'd placed tmpl/*.sgml after the ':' rather
than before it.

Hmm. That looks pretty sneaky. It does seem to work, though I don't know make
well enough to know if there will be any strange side-effects.
Unless a make expert says it is OK I don't really fancy applying it, as it
looks a bit too hackish to me.

Using "$(srcdir)/tmpl/*.sgml" may be better as well.
Comment 4 Simon Josefsson 2004-10-31 14:55:30 UTC
Yes, I'm also dubious how clean and portable this is.

However, what do you think in general of a rewrite of gtk-doc.make?  There is a
reported bug about build failures for objdir != srcdir, and there is this
problem.  I used to write my own makefile, see:

http://josefsson.org/cgi-bin/viewcvs.cgi/libidn/doc/reference/Makefile.am?rev=1.10&view=markup

But I didn't know how to make hem generate *.devhelp files, and I thought it
generally would be better if I used your recommended files and reported bugs
about it.

I'm not sure I can volunteer to work on this (and I probably wouldn't do a good
job, as I'm not familiar with GTK-DOC).  Thought I just report what I would want
to happen, FYI.

Thanks.
Comment 5 Geert Stappers 2004-11-01 13:49:15 UTC
The 'objdir != srcdir' bugreport is bug 127049.
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2005-08-24 17:31:23 UTC
see http://www.gnu.org/software/make/manual/html_mono/make.html#SEC28

this IMHO we can use
+tmpl-build.stamp $(srcdir)/tmpl/*.sgml: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES)
Comment 7 Geert Stappers 2005-08-24 20:27:53 UTC
> ------- Additional Comment #3 From Damon Chaplin  2004-10-31 14:31 UTC -------
>
> Ah, I misread your patch. I thought you'd placed tmpl/*.sgml after the ':'
> rather than before it.
>
> Hmm. That looks pretty sneaky. It does seem to work, though I don't know make
> well enough to know if there will be any strange side-effects.
> Unless a make expert says it is OK I don't really fancy applying it, as it
> looks a bit too hackish to me.

 http://www.gnu.org/software/make/manual/html_mono/make.html#SEC28
says: The targets are file names, separated by spaces. Wildcard characters may
be used


I have it seen working before and to Stefan I know now why.
Comment 8 Geert Stappers 2005-08-24 20:41:54 UTC
Created attachment 51286 [details] [review]
my conclusion of the bugreport

For the colon two space separated files
and $(srcdir) in the path

(the patch is against current CVS)
Comment 9 Damon Chaplin 2005-08-24 21:12:12 UTC
The thing I don't like is that it relies on the strange make behavior that if
a glob matches no files it just returns the original glob string.
i.e. there are no files in the tmpl originally, so the "tmpl/*.sgml" glob
returns "tmpl/*.sgml".

I think we'll probably need a separate makefile for apps that don't want to
use tmpl/* files, so this could be fixed there.
Comment 10 Geert Stappers 2005-08-24 22:32:09 UTC
> 2004-10-27 21:45
> Reporter: simon@josefsson.org (Simon Josefsson)
>
> I don't have any files in CVS inside tmpl/, so I get a warning during make (see
> below).  It is slightly surprising, because after make dies, there are
> tmpl/'.sgml files.  I suspect make tests for the files too early.  This patch
> let make know about the dependency better:


I have the unpleasant feeling that we are back at square one.
Comment 11 Stefan Sauer (gstreamer, gtkdoc dev) 2005-12-07 17:42:50 UTC
the probably most hacky workaround is to precreate the 'tmpl' dir and put an
empty file named '_gtkdoc.sgml' in there.
Comment 12 Damon Chaplin 2005-12-08 20:52:11 UTC
It's still a kludgy fix, though. (A simpler kludgy fix is to just add a single
tmpl/dummy.sgml file to cvs.)

I'd rather have a way to use gtk-doc without template files at all.
That would need a new set of (hopefully much simple) make rules.

The application Makefile.am could set a variable, e.g. "GTK_DOC_NO_TEMPLATES=1"
and the gtk-doc.make file could use this to switch to the new make rules.
Comment 13 Benjamin Otte (Company) 2007-03-16 22:54:51 UTC
Another dodgy workaround is to add

tmpl/*.sgml:
        @true

to gtk-doc.make.

At least it works when i put it inside my Makefile.am.
Comment 14 Stefan Sauer (gstreamer, gtkdoc dev) 2007-04-04 08:21:54 UTC
Another workarount has been sent to me by Tommi Komulainen

tmpl_files := $(wildcard $(srcdir)/tmpl/*.sgml)

sgml-build.stamp: [...] $(tmpl_files) [...]

I tested it and it works fine for me too.

This change is also what is suggested in 
http://www.gnu.org/software/make/manual/html_node/Wildcard-Pitfall.html#Wildcard-Pitfall
http://www.gnu.org/software/make/manual/html_node/Wildcard-Function.html#Wildcard-Function

I searched the web up and down, but found nothing saying that this is gnu-make related (I e.g. looked into http://www.gnu.org/software/make/manual/html_node/Features.html#Features).

@Daemon: is it okay to apply it?
Comment 15 Yeti 2007-04-17 19:04:54 UTC
(In reply to comment #14)
> tmpl_files := $(wildcard $(srcdir)/tmpl/*.sgml)
> ...
> I searched the web up and down, but found nothing saying that this is gnu-make
> related...

It is, all the $(functions ) are GNU.  Just try it on *BSD.

Not having any manually-written information in tmpl files fixes this problem (one can get rid of tmpl/*.sgml dependency because the content of tmpl/ cannot change independently of the stamps).  And this is what anyone using a version control system wants anyway because the only worse mess caused by mix of generation and hand-editing than this are gettext's PO files.  Maybe it is a bit radical, but I would just deprectate hand-edited tmpl/*.sgml files...
Comment 16 Yeti 2007-04-17 21:28:46 UTC
(In reply to comment #14)
> looked into
> http://www.gnu.org/software/make/manual/html_node/Features.html#Features

It is there:

The remaining features are inventions new in GNU make:
...
* Manipulate text by calling functions. See Functions for Transforming Text.
...

the link text says `Functions for Transforming Text', perhaps these were the first implemented, however it evidently applies (and points) to functions generally.
Comment 17 Stefan Sauer (gstreamer, gtkdoc dev) 2007-04-18 07:14:52 UTC
Can we just generate the gtk-doc.make depending wheter the user has tmpl files? if there are no tmpl files in the checkout we don't add the $(srcdir)/tmpl/*.sgml dependency?
Comment 18 Stefan Sauer (gstreamer, gtkdoc dev) 2007-04-18 11:58:22 UTC
that was too quick, as this would only work for a clean checkout :/ So what about a flag to gtkdocize then.
Comment 19 Damon Chaplin 2007-04-18 13:01:01 UTC
We do need some way to have a separate set of Make rules for projects with
and without template files.

The ideal thing would be a conditional test within gtk-doc.make, but I
can't think of an easy way to do that. GNU make conditionals may not be
portable (noone seems to use them), and automake conditionals need to be
setup in configure.in.

A flag to gtkdocize to tell it to use an alternative gtk-doc.make file
may be OK. Though we'd also need to update the GTK_DOC_CHECK macro
somehow.
Comment 20 Stefan Sauer (gstreamer, gtkdoc dev) 2007-04-28 20:24:28 UTC
idea #1:
would it help if we install gtkdoc.make.in and conditionally generate gtkdoc.make depending on some flags that the project maintainer can set in configure.ac.

idea #2:
could we set some conditionals in Makefile.am (where gtkdoc.make is included) and based on the conditional use different rules. (I would need to work also if the consitionals aren't set.)
Comment 21 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-12 06:12:18 UTC
I've tried this again and vote for the solution in comment #13. Its portable and it works. We should add a comment there explaining the hack though. Okay if I do this?
Comment 22 Yeti 2007-07-12 07:57:21 UTC
What exactly you mean by portable?  I tried to verify this with gstreamer on FreeBSD -- until I realized it uses modified gtk-doc.make for template-free operation too (which reasonably-sized package actually uses the stock gtk-doc.make?).  So instead I found bug 456154 which (together with comment 17) made me a bit suspicious to your Makefile portability claims...

Also, since I hope template-free operation is the future, I'd prefer to have the possibility to get a truly template-free makefile.
Comment 23 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-12 08:14:44 UTC
Yeti,

the core problem here is this rule in gtkdoc.make

sgml-build.stamp: tmpl.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files)

if make is run for the first time $(srcdir)/tmpl/ is empty and thus the glob does not expand. make end up looking for a rule to build a file named "$(srcdir)/tmpl/*.sgml" and fails.

Using
tmpl_files := $(wildcard $(srcdir)/tmpl/*.sgml)
is gnu-make specific. But having the dummy target is not.
Comment 24 Yeti 2007-07-12 08:34:55 UTC
Having a dummy target is definitely portable.  However, handling of wildcards (i.e. when and how they are exactly expanded) may exhibit various peculiarities.  

Consider for instance an empty directory with the following Makefile

x: *.sgml
	@echo "Building x"
	@date >x

*.sgml:
	@echo "SGML"

Invoking GNU make there prints

SGML
Building x

and the second invocation prints again

SGML
Building x

Whereas BSD make prints

Building x

for the first time and

`x' is up to date.

in the second invocation.

In other words it works, but for *completely different reasons*.
Comment 25 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-12 08:59:10 UTC
Yes I was afraid of something like this. I run the build once again (gnumake), but it did not do anything (but neither said that there is nothing to do).
Do you have any better idea? Are you on irc? We could discuss there. Im am as 'ensonic' on freenode/gimpnet.
Comment 26 Yeti 2007-07-12 10:56:32 UTC
(In reply to comment #25)
> Do you have any better idea?

Well, while the dummy rule might not be completely portable, it seems to be at least an improvement against the current state.

I suggest to

1. Add an option --no-tmpl (or something like that) to gtkdocize to select template-free operation.  Easy.

2. Split gtk-doc.make to two versions.  Easy.

3. Add the rule from comment 13 to the tmpl-employing one. Easy.

4. Remove the wildcard dependency from the tmpl-free one, also add

distclean-local:
	rm -rf tmpl

there and stop distributing tmpl/.  (Can we do the same with xml/?  I do, but I use a very aggressive rebuilding approach, I'm not sure now whether it can be done generally.  Anyway, this is probably not relevant right now.)  Needs some testing.

I can prepare a patch for this.

------------------------------

This way we get a complete fix for template-free operation, which is what the original bug report is about.

In addition, the situation should improve for the first build for people who like revision system conflicts and keep information in tmpl/, as the rule from comment 13 seems to fix the problem with GNU make and not make it worse with BSD make.  I don't know much about other makes, I suppose it should at least not make it worse either. 

> Are you on irc?

About once in ten years...

> We could discuss there.

If necessary...
Comment 27 Stefan Sauer (gstreamer, gtkdoc dev) 2007-07-15 12:44:07 UTC
*** Bug 452461 has been marked as a duplicate of this bug. ***
Comment 28 Stefan Sauer (gstreamer, gtkdoc dev) 2007-08-09 17:54:40 UTC
In bug #338068 I propose a gtkdoc.make for a template free build (that wont have this issue). This needs a parameter for gtkdocize anyway (to copy a different gtkdoc.make). What about shipping a patch (or another version) to the normal gtkdoc.make (tmpl based) that fixes this for gnu-make users that uses the method from comment #14.

gtkdocize would that have a parameter --flavour={no-tmpl,gmake,old} - better names are welcome.
Comment 29 Yeti 2007-08-09 19:33:44 UTC
Isn't using GNU make constructs in Makefile.am a bit perverse?

Most of what automake does is working around the lack/incompatible implementation of pattern rules, includes, conditionals, functions and other features in various makes.  The rest is a rule library (namely to conform GNU coding standards) that could be also easily provided assuming GNU make.  So, you use a complex makefile preprocessor that puts lots of constrains on the conventions in your makefiles to achieve portability, and then you spoil it by requiring GNU make.

Please, don't do things like adding options for creating Makefile.am that require on GNU make.  And we know the suggestion in comment 14 creates such requirement, as without GNU make you get empty tmpl_files and therefore wrong dependencies.

The dummy target

tmpl/*.sgml:
        @true

on the other hand has a relatively good chance to work with other implementations as you don't actually care whether the dummy rule gets executed (as with GNU make which keeps *.sgml unexpanded when nothing matches) or not (as with BSD make that more logically expands non-matching globs to nothing); the point is just to make make shut up.
Comment 30 Stefan Sauer (gstreamer, gtkdoc dev) 2007-08-11 14:03:20 UTC
SVN now also has a gtk-doc.make without this that not builds/creates and tmpl files at all.

2007-08-11  Stefan Kost  <ensonic@users.sf.net>

	* gtk-doc.make:
	  Add dummy rule to make first build run through. Fixes #156643