Re: git: 0a0f7486413c - main - man: Build manpages for all architectures

Reply: Andriy Gapon : "Re: git: 0a0f7486413c - main - man: Build manpages for all architectures"
In reply to: Andriy Gapon : "Re: git: 0a0f7486413c - main - man: Build manpages for all architectures"
Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Baptiste Daroussin <bapt_at_FreeBSD.org>
Date: Thu, 25 Nov 2021 14:23:39 UTC
On Thu, Nov 25, 2021 at 03:57:41PM +0200, Andriy Gapon wrote:
> 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) ?
> 
Hardlink not in the same directory is imho a fragile setup anyway, what if a
user has different mount points here, the hardlink would be broken. while there
is little chances someone is doing that, history told me people are doing weird
things and if they haven't yet, they will soon.

I continue to think this kind of links should be 1/ symlinks, 2/ relative
symlinks if they are in a situation which can become a cross device issue.

Best regards,
Bapt