Re: git: 0a0f7486413c - main - man: Build manpages for all architectures
Date: Thu, 25 Nov 2021 13:57:41 UTC
On 06/07/2021 12:03, Baptiste Daroussin wrote:
> On Wed, Jun 30, 2021 at 08:06:51AM +0000, Fernando Apesteguía wrote:
>> The branch main has been updated by fernape (doc, ports committer):
>>
>> URL: https://cgit.FreeBSD.org/src/commit/?id=0a0f7486413c147d56808b38055c40c64cff61f5
>>
>> commit 0a0f7486413c147d56808b38055c40c64cff61f5
>> Author: Fernando Apesteguía <fernape@FreeBSD.org>
>> AuthorDate: 2021-06-09 10:58:04 +0000
>> Commit: Fernando Apesteguía <fernape@FreeBSD.org>
>> CommitDate: 2021-06-30 07:57:51 +0000
>>
>> man: Build manpages for all architectures
>>
>> Building and installing architecture-specific man pages only raises a number of
>> problems:
>>
>> * The https://www.freebsd.org/cgi/man.cgi is incomplete. As an
>> example, it does not show results for pae(4). The reason for this is
>> that the cgi interface runs on FreeBSD amd64.
>>
>> * In FreeBSD amd64 some manual pages have broken X-refs. See hptrr(4)
>> for an example.
>>
>> * Also, we have broken links in our Release Notes. This is a
>> consequence of the first point. See
>> https://www.freebsd.org/releases/13.0R/hardware/#proc-i386.
>>
>> Make MAN_ARCH default to 'all' so we build all the man pages for all the
>> architectures. The difference in disk space is negligible. Also link
>> architecture-specific man pages to their own section while keeping their own
>> namespace.
>>
>> PR: 212290
>> Reported by: mj@bsdops.com
>> Approved by: ceri@, wosch@
>> MFC after: 4 weeks
>> ---
>> sbin/Makefile | 6 ++++++
>> share/man/man4/Makefile | 4 +---
>> share/man/man4/man4.aarch64/Makefile | 5 +++++
>> share/man/man4/man4.arm/Makefile | 5 +++++
>> share/man/man4/man4.i386/Makefile | 5 +++++
>> share/man/man4/man4.powerpc/Makefile | 5 +++++
>> share/man/man5/make.conf.5 | 2 +-
>> usr.sbin/Makefile | 7 +++++++
>> usr.sbin/apm/Makefile | 4 ++++
>> 9 files changed, 39 insertions(+), 4 deletions(-)
>>
>> diff --git a/sbin/Makefile b/sbin/Makefile
>> index 64840bae82bb..f53e2f037ebe 100644
>> --- a/sbin/Makefile
>> +++ b/sbin/Makefile
>> @@ -90,6 +90,12 @@ SUBDIR.${MK_ZFS}+= zfsbootcfg
>>
>> SUBDIR.${MK_TESTS}+= tests
>>
>> +# Add architecture-specific manpages
>> +# to be included anyway
>> +MAN= sconfig/sconfig.8
>> +
>> +.include <bsd.prog.mk>
>> +
>> .include <bsd.arch.inc.mk>
>>
>> SUBDIR_PARALLEL=
>> diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
>> index 5051470edc71..9027fe7df841 100644
>> --- a/share/man/man4/Makefile
>> +++ b/share/man/man4/Makefile
>> @@ -895,9 +895,7 @@ _cgem.4= cgem.4
>> MLINKS+=cgem.4 if_cgem.4
>> .endif
>>
>> -.if empty(MAN_ARCH)
>> -__arches= ${MACHINE} ${MACHINE_ARCH} ${MACHINE_CPUARCH}
>> -.elif ${MAN_ARCH} == "all"
>> +.if empty(MAN_ARCH) || ${MAN_ARCH} == "all"
>> __arches= ${:!/bin/sh -c "/bin/ls -d ${.CURDIR}/man4.*"!:E}
>> .else
>> __arches= ${MAN_ARCH}
>> diff --git a/share/man/man4/man4.aarch64/Makefile b/share/man/man4/man4.aarch64/Makefile
>> index 6714a47011ef..ef5fcd84ccd4 100644
>> --- a/share/man/man4/man4.aarch64/Makefile
>> +++ b/share/man/man4/man4.aarch64/Makefile
>> @@ -17,6 +17,11 @@ MAN= \
>> rk_i2c.4 \
>> rk_pinctrl.4 \
>>
>> +# Link files to the parent directory
>> +.for _manpage in ${MAN}
>> +MLINKS+=${_manpage} ../${_manpage}
>> +.endfor
>
> This breaks make -DNO_ROOT in a subtle manner and so likely pkgbase.
>
> The right way to do it is to add something that uses INSTALL_RSYMLINK or alike.
I looked a bit into this and I think that the change does nothing wrong, we just
populate METALOG incorrectly. After all, for hardlinks the source and target
are interchangeable, they are two names for the same file.
Maybe we could fix the issue in the place where mtree entries are created for
hardlinks?
Baring that, one easy way to work around the issue of having .. in paths is to
install architecture manpage links in the opposite order: first install a
manpage to a main directory, then create a hardlink in an architecture
sub-directory.
As a proof of concept, I implemented that idea for man4.arm and man4.aarch:
https://people.freebsd.org/~avg/man-arch-links.diff
And here is a sample of entries from METALOG produced with the change:
./usr/share/man/man4/rk_gpio.4.gz type=file uname=root gname=wheel mode=0444
size=1075 tags=package=utilities
./usr/share/man/man4/aarch64/rk_gpio.4.gz type=file uname=root gname=wheel
mode=0444 size=1075 tags=package=utilities
./usr/share/man/man4/aw_gpio.4.gz type=file uname=root gname=wheel mode=0444
size=1253 tags=package=utilities
./usr/share/man/man4/imx_wdog.4.gz type=file uname=root gname=wheel mode=0444
size=1867 tags=package=utilities
./usr/share/man/man4/imxwdt.4.gz type=file uname=root gname=wheel mode=0444
size=1867 tags=package=utilities
./usr/share/man/man4/arm/imxwdt.4.gz type=file uname=root gname=wheel mode=0444
size=1867 tags=package=utilities
./usr/share/man/man4/arm/aw_gpio.4.gz type=file uname=root gname=wheel mode=0444
size=1253 tags=package=utilities
./usr/share/man/man4/arm/imx_wdog.4.gz type=file uname=root gname=wheel
mode=0444 size=1867 tags=package=utilities
Looking at the output I got another thought: do we need architecture sub-dir
links at all now that we install manpages to a main directory?
Is there any benefit to having the same manpage in a directory (like man4) and
its immediate subdirectory (like man4/arm) ?
--
Andriy Gapon