netdev - Re: [PATCH bpf-next] bpftool: fix build failure

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date:   Mon, 14 Sep 2020 09:46:45 -0700
From:   Yonghong Song <yhs@...com>
To:     Quentin Monnet <quentin@...valent.com>, <bpf@...r.kernel.org>,
        <netdev@...r.kernel.org>
CC:     Alexei Starovoitov <ast@...nel.org>,
        Daniel Borkmann <daniel@...earbox.net>, <kernel-team@...com>
Subject: Re: [PATCH bpf-next] bpftool: fix build failure



On 9/14/20 1:16 AM, Quentin Monnet wrote:
> On 14/09/2020 07:12, Yonghong Song wrote:
>> When building bpf selftests like
>>    make -C tools/testing/selftests/bpf -j20
>> I hit the following errors:
>>    ...
>>    GEN      /net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-gen.8
>>    <stdin>:75: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
>>    <stdin>:71: (WARNING/2) Literal block ends without a blank line; unexpected unindent.
>>    <stdin>:85: (WARNING/2) Literal block ends without a blank line; unexpected unindent.
>>    <stdin>:57: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
>>    <stdin>:66: (WARNING/2) Literal block ends without a blank line; unexpected unindent.
>>    <stdin>:109: (WARNING/2) Literal block ends without a blank line; unexpected unindent.
>>    <stdin>:175: (WARNING/2) Literal block ends without a blank line; unexpected unindent.
>>    <stdin>:273: (WARNING/2) Literal block ends without a blank line; unexpected unindent.
>>    make[1]: *** [/net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-perf.8] Error 12
>>    make[1]: *** Waiting for unfinished jobs....
>>    make[1]: *** [/net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-iter.8] Error 12
>>    make[1]: *** [/net-next/tools/testing/selftests/bpf/tools/build/bpftool/Documentation/bpftool-struct_ops.8] Error 12
>>    ...
>>
>> I am using:
>>    -bash-4.4$ rst2man --version
>>    rst2man (Docutils 0.11 [repository], Python 2.7.5, on linux2)
>>    -bash-4.4$
>>
>> Looks like that particular version of rst2man prefers to have a blank line
>> after literal blocks. This patch added block lines in related .rst files
>> and compilation can then pass.
>>
>> Cc: Quentin Monnet <quentin@...valent.com>
>> Fixes: 18841da98100 ("tools: bpftool: Automate generation for "SEE ALSO" sections in man pages")
>> Signed-off-by: Yonghong Song <yhs@...com>
> 
> 
> Hi Yonghong, thanks for the fix! I didn't see those warnings on my
> setup. For the record my rst2man version is:
> 
> 	rst2man (Docutils 0.16 [release], Python 3.8.2, on linux)
> 
> Your patch looks good, but instead of having blank lines at the end of
> most files, could you please check if the following works?

Thanks for the tip! I looked at the generated output again. My above fix 
can silent the warning, but certainly not correct.

With the following change, I captured the intermediate result of the 
.rst file.

  ifndef RST2MAN_DEP
         $(error "rst2man not found, but required to generate man pages")
  endif
-       $(QUIET_GEN)( cat $< ; echo -n $(call see_also,$<) ) | rst2man 
$(RST2MAN_OPTS) > $@
+       $(QUIET_GEN)( cat $< ; echo -n $(call see_also,$<) ) | tee 
/tmp/tt | rst2man $(RST2MAN_OPTS) > $@

With below command,
    make clean && make bpftool-cgroup.8
I can get the new .rst file for bpftool-cgroup.

At the end of file /tmp/tt (changed bpftool-cgroup.rst), I see

     ID       AttachType      AttachFlags     Name
\n SEE ALSO\n========\n\t**bpf**\ (2),\n\t**bpf-helpers**\ 
(7),\n\t**bpftool**\ (8),\n\t**bpftool-btf**\ 
(8),\n\t**bpftool-feature**\ (8),\n\t**bpftool-gen**\ 
(8),\n\t**bpftool-iter**\ (8),\n\t**bpftool-link**\ 
(8),\n\t**bpftool-map**\ (8),\n\t**bpftool-net**\ 
(8),\n\t**bpftool-perf**\ (8),\n\t**bpftool-prog**\ 
(8),\n\t**bpftool-struct_ops**\ (8)\n

This sounds correct if we rst2man can successfully transforms '\n'
or '\t' to proper encoding in the man page.

Unfortunately, with my version of rst2man, I got

.IP "System Message: WARNING/2 (<stdin>:, line 146)"
Literal block ends without a blank line; unexpected unindent.
.sp
n SEE 
ALSOn========nt**bpf**(2),nt**bpf\-helpers**(7),nt**bpftool**(8),nt**bpftool\-btf**(8),nt**bpftool\-feature**(8),nt**bpftool\-gen**(8),nt**bpftool\-iter**(8),nt**bpftool\-link**(8),nt**bpftool\-map**(8),nt**bpftool\-net**(8),nt**bpftool\-perf**(8),nt**bpftool\-prog**(8),nt**bpftool\-struct_ops**(8)n
.\" Generated by docutils manpage writer.

The rst2man simply considered \n as 'n'. The same for '\t' and
this caused the issue.

I did not find a way to fix the problem yet.

> 
> ------
> 
> diff --git a/tools/bpf/bpftool/Documentation/Makefile
> b/tools/bpf/bpftool/Documentation/Makefile
> index 4c9dd1e45244..01b30ed86eac 100644
> --- a/tools/bpf/bpftool/Documentation/Makefile
> +++ b/tools/bpf/bpftool/Documentation/Makefile
> @@ -32,7 +32,7 @@ RST2MAN_OPTS += --verbose
> 
>   list_pages = $(sort $(basename $(filter-out $(1),$(MAN8_RST))))
>   see_also = $(subst " ",, \
> -       "\n" \
> +       "\n\n" \
>          "SEE ALSO\n" \
>          "========\n" \
>          "\t**bpf**\ (2),\n" \
>