Re: Couple of gtk-doc glitches

[Roman Bogorodskiy]

  Roman Bogorodskiy wrote:

>   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

I think I've made some progress with the debugging, however, I'm not
sure I understand the results.

As I wrote before, when building from git, I see error messages about
libtasn1-sections.txt:

../../lib/includes/libtasn1.h:24: warning: Section libtasn1 is not defined in 
the libtasn1-sections.txt file.

And this file is actually empty. As I mentioned earlier as well, I don't
have this error when I build from port.
I've checked the dist tarball and libtasn1-sections.txt is populated there.
So even if gtkdoc-scan fails with:

../../lib/includes/libtasn1.h:0: warning: partial declaration (struct) :   
struct asn1_data_node_st

it doesn't affect the build because the section file already exists.

Trying to figure out why this partial declaration error shows up leads
to strange results. This struct looks this way:

291   struct asn1_data_node_st
292   {
293     const char *name;           /* Node name */
294     const void *value;          /* Node value */
295     unsigned int value_len;     /* Node value size */
296     unsigned int type;          /* Node value type (ASN1_ETYPE_*) */
297   };
298   typedef struct asn1_data_node_st asn1_data_node_st;

If I understood gtkdoc-scan code correctly, it looks like it cannot find
the terminating '};'. From what I can see, it doesn't allow extra spaces
here:

https://gitlab.gnome.org/GNOME/gtk-doc/-/blob/master/gtkdoc/scan.py#L944

as the regexp it uses is:

   sm = re.search(r'\n\}\s*(?:(\w+)?%s)?;\s*$' % optional_decorators_regex, 
decl)

Interestingly, few lines above the same code allows extra spaces for
enums:

https://gitlab.gnome.org/GNOME/gtk-doc/-/blob/master/gtkdoc/scan.py#L923

When I add "\s*" before "\}", gtkdoc-scan works fine and the build
succeeds.

To confirm that, I've also rolled back my regexp changes and updated the
header:

diff --git a/lib/includes/libtasn1.h.in b/lib/includes/libtasn1.h.in
index 94a1881..57ac5a1 100644
--- a/lib/includes/libtasn1.h.in
+++ b/lib/includes/libtasn1.h.in
@@ -294,7 +294,7 @@ extern "C"
     const void *value;         /* Node value */
     unsigned int value_len;    /* Node value size */
     unsigned int type;         /* Node value type (ASN1_ETYPE_*) */
-  };
+};
   typedef struct asn1_data_node_st asn1_data_node_st;

 /***********************************/

With this change and unmodified gtkdoc-scan build also succeeds. I'm
using gtk-doc 1.33.2 which appears to be the latest version.

So I'm curious how it works on your system: are you using gtk-doc 1.33.2
as well or maybe have some extra patches for it? Or maybe the actual
reason is deeper than that.

Roman Bogorodskiy

signature.asc
Description: PGP signature