Re: Couple of gtk-doc glitches

[Roman Bogorodskiy]

  Simon Josefsson wrote:

> Roman Bogorodskiy <bogorodskiy@gmail.com> writes:
> 
> > Hi,
> >
> > I was updating a FreeBSD port of libtasn1 to 4.18.0 and noticed the
> > build fails with:
> 
> Hi Roman.  Thanks for the report!
> 
> > 1. Force using GNU make instead of a BSD make
> 
> BSD make should work, or it is a bug.  I wouldn't blame you for going
> with the simple solution, though, but we should try to get this fixed...
> 
> > 2. Patch it with:
> >
> >  install  -m 0644 ./html/libtasn1.devhelp2
> >  install  -m 0644 ./html/right-insensitive.png
> > --- doc/reference/Makefile.in.orig      2021-11-13 05:59:58 UTC
> > +++ doc/reference/Makefile.in
> > @@ -1840,7 +1840,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(c
> >           test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file 
> > $(abs_builddir)/html; \
> >           test -f $$file && cp $$file $(abs_builddir)/html; \
> >         done;
> > -       $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) 
> > --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
> > +       cd "$(abs_srcdir)" && $(GTK_DOC_V_XREF)gtkdoc-fixxref 
> > --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) 
> > $(FIXXREF_OPTIONS)
> >         $(AM_V_at)touch html-build.stamp
> >  
> >  pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) 
> > $(expand_content_files)
> >
> > Apparently, gtkdoc-fixxref needs to be executed from $(abs_srcdir),
> > which is the case when building with GNU make, but with BSD make working
> > directory is $(abs_srcdir)/html.
> 
> Interesting -- why is CWD in html/ here?  The previous command in the
> makefile does 'cd html && ...' in the beginning, but that shouldn't
> affect the CWD for the next command, should it?

Apparently, this behaviour depends on the mode. There's something in man
make(1) about it https://www.freebsd.org/cgi/man.cgi?make(1):

     Makefiles should be written so that the mode of make operation does not
     change their behavior.  For example, any command which needs to use "cd"
     or "chdir" without potentially changing the directory for subsequent com-
     mands should be put in parentheses so it executes in a subshell.  To
     force the use of one shell, escape the line breaks so as to make the
     whole script one command.  For example:

           avoid-chdir-side-effects:
                   @echo Building $@ in `pwd`
                   @(cd ${.CURDIR} && ${MAKE} $@)
                   @echo Back in `pwd`

           ensure-one-shell-regardless-of-mode:
                   @echo Building $@ in `pwd`; \
                   (cd ${.CURDIR} && ${MAKE} $@); \
                   echo Back in `pwd`

     Since make will chdir(2) to `.OBJDIR' before executing any targets, each
     child process starts with that as its current working directory.

I can see that with the following test:

$ cat dir-test.make     
test!
        @cd /tmp && echo `pwd`
        @echo `pwd`
$ make -f dir-test.make test    
/tmp
/usr/obj/usr/home/novel
$ make -f dir-test.make -j2 test
--- test ---
/tmp
/tmp
$

> > Patching Makefile.in is when building from a dist tarball, but a more
> > general fix probably should go into gtk-doc.make, and here comes the
> > second issue.
> 
> Thanks for working your way through this maze...
> 
> > When I try to build it from the git repo, I get:
> >
> >   DOC   Introspecting gobjects
> >   DOC   Building XML
> >   DOC   Building XML
> > ../../lib/includes/libtasn1.h:24: warning: Section libtasn1 is not defined 
> > in the libtasn1-sections.txt file.
> > ../../lib/includes/libtasn1.h:24: warning: Section libtasn1 is not defined 
> > in the libtasn1-sections.txt file.
> > ./libtasn1-unused.txt:1: warning: 95 unused declarations. They should be 
> > added to libtasn1-sections.txt in the appropriate place.
> >   DOC   Building HTML
> > warning: failed to load external entity "../xml/libtasn1.xml"
> > ../libtasn1-docs.xml:34: element include: XInclude error : could not load 
> > ../xml/libtasn1.xml, and no fallback was found
> > gmake[3]: *** [Makefile:1824: html-build.stamp] Error 6
> >
> > Before that I can see that gtkdoc-scan is complaining about:
> >
> > ../../lib/includes/libtasn1.h:0: warning: partial declaration (struct) :   
> > struct asn1_data_node_st
> >
> > However, I can see the same message when building from the dist tarball.
> > Also, comparing the failing build from a git checkout and a successful
> > build from the dist tarball, I can see that
> > ./doc/reference/libtasn1-sections.txt is empty for the failing build,
> > and the successful build has it populated.
> >
> > For the git checkout build I don't apply any patches and use GNU make.
> >
> > Any thoughts what's going on here?
> 
> I recall seeing this error too, and I think it was because of
> objdir!=srcdir issues and it couldn't locate the libtasn1.h header file
> properly for the scanning.  Just an idea.
> 
> Did you try git master?  I did some builddir!=srcdir fixes in git after
> the 4.18.0 release since I probably ran into something similar that you
> did.

Yes, trying git master. Also, I guess in my case builddir==srcdir,
because in the toplevel dir I run ./bootstrap, then ./configure
--enable-gtk-doc, followed by 'gmake' in the same dir (gmake is a GNU
make).

Same result when checking out tag v4.18.0 in the git working directory.

I guess I should try comparing build logs from the port (which for some
reason works fine except that it needs the cd "$(abs_srcdir)" trick or
gmake as I described above) and see what's different...
 
> I'll try to reproduce this... having a BSD system in the CI/CD test
> framework would really help iron out more of the GNU/Linux idioms that
> tends to be used.
> 
> /Simon

Please let me know if I can help with that.

Roman Bogorodskiy

signature.asc
Description: PGP signature