Paths

Table of Contentst

man: Build manpages for all architectures
ClosedPublic
Actions

Authored by fernape on Jun 10 2021, 11:53 AM.

Details

Reviewers

• ian
ceri
wosch

Group Reviewers

manpages

Commits

rG0a0f7486413c: man: Build manpages for all architectures

Summary

Building and installing _only_ architecture-specific man pages 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 (suggested by ceri@).

Some discussion took place here

PR: 212290

Test Plan

Apply patch
cd <top_source_dir>/share/man/man4 && make && make install
Do a man pae. The page is available as a general manpage so man -m is not needed.
Check with ls -i that man4/pae.4 and man4/i386/pae.4 are the same file

Diff Detail

Repository

rS FreeBSD src repository - subversion

Lint

Lint Passed

Unit

No Test Coverage

Build Status

Buildable 39998
Build 36887: arc lint + arc unit

Event Timeline

fernape created this revision.Jun 10 2021, 11:53 AM

Herald added a reviewer: manpages. · View Herald TranscriptJun 10 2021, 11:53 AM

Herald added subscribers: Contributor Reviews (src), emaste, andrew, imp. · View Herald Transcript

fernape requested review of this revision.Jun 10 2021, 11:53 AM

Harbormaster completed remote builds in B39830: Diff 90693.Jun 10 2021, 11:53 AM

fernape edited the summary of this revision. (Show Details)Jun 10 2021, 12:20 PM

fernape added reviewers: • ian, ceri.

Looks good - have also tested with some (fake) conflicting files and the right thing happens.

This revision is now accepted and ready to land.Jun 10 2021, 2:42 PM

wosch added a subscriber: wosch.Jun 13 2021, 1:03 PM

The patch looks promising. But there are still some manual pages missing as

share/man/man8/powerpc/nvram.8.gz
share/man/man8/*/apm.8.gz
share/man/man8/*/apmconf.8.gz
share/man/man8/i386/apmd.8.gz
share/man/man8/i386/sconfig.8.gz

This revision now requires changes to proceed.Jun 13 2021, 1:07 PM

In D30715#691201, @wosch wrote:

The patch looks promising. But there are still some manual pages missing as

share/man/man8/powerpc/nvram.8.gz
share/man/man8/*/apm.8.gz
share/man/man8/*/apmconf.8.gz
share/man/man8/i386/apmd.8.gz
share/man/man8/i386/sconfig.8.gz

Those pages are listed in src/ObsoleteFiles.inc and does not seem to get installed in a new installation. At least not in my -CURRENT.

I understand building with something like MK_APM=yes will not remove the apm* man pages installed previously?

In D30715#691563, @fernape wrote:

In D30715#691201, @wosch wrote:

The patch looks promising. But there are still some manual pages missing as

share/man/man8/powerpc/nvram.8.gz
share/man/man8/*/apm.8.gz
share/man/man8/*/apmconf.8.gz
share/man/man8/i386/apmd.8.gz
share/man/man8/i386/sconfig.8.gz

Those pages are listed in src/ObsoleteFiles.inc and does not seem to get installed in a new installation. At least not in my -CURRENT.

Are you sure? Please check the correct pathes, e.g.

egrep share/man/man8/i386/sconfig.8.gz ObsoleteFiles.inc

returns zero hits for FreeBSD-14-current (main branch).

Second, you are aware that you have to patch stable/13 and stable/12 as well? Otherwise the fixes will be not part of our next supported releases.

In D30715#691587, @wosch wrote:

In D30715#691563, @fernape wrote:

In D30715#691201, @wosch wrote:

The patch looks promising. But there are still some manual pages missing as

share/man/man8/powerpc/nvram.8.gz
share/man/man8/*/apm.8.gz
share/man/man8/*/apmconf.8.gz
share/man/man8/i386/apmd.8.gz
share/man/man8/i386/sconfig.8.gz

Those pages are listed in src/ObsoleteFiles.inc and does not seem to get installed in a new installation. At least not in my -CURRENT.

Are you sure? Please check the correct pathes, e.g.

egrep share/man/man8/i386/sconfig.8.gz ObsoleteFiles.inc

returns zero hits for FreeBSD-14-current (main branch).

You're right:

~src$ find . -name Makefile -exec grep -H MANSUBDIR {} \;
./sbin/sconfig/Makefile:MANSUBDIR= /i386
./share/man/man4/man4.aarch64/Makefile:MANSUBDIR=/aarch64
./share/man/man4/man4.arm/Makefile:MANSUBDIR=/arm
./share/man/man4/man4.i386/Makefile:MANSUBDIR=/i386
./share/man/man4/man4.powerpc/Makefile:MANSUBDIR=/powerpc
./usr.sbin/apm/Makefile:MANSUBDIR= /${MACHINE_CPUARCH}
./usr.sbin/apmd/Makefile:MANSUBDIR= /i386
./usr.sbin/nvram/Makefile:MANSUBDIR= /powerpc

Things under man4 are already covered by the patch. Things outside that directory are not.

I'll have a look at it.

Second, you are aware that you have to patch stable/13 and stable/12 as well? Otherwise the fixes will be not part of our next supported releases.

Well... no. I am not aware of the policy for merging changes like this to stable releases. Would it be necessary/desirable/mandatory? Note I am not a src committer.

Thanks!

You're right:

~src$ find . -name Makefile -exec grep -H MANSUBDIR {} \;
./sbin/sconfig/Makefile:MANSUBDIR= /i386
./share/man/man4/man4.aarch64/Makefile:MANSUBDIR=/aarch64
./share/man/man4/man4.arm/Makefile:MANSUBDIR=/arm
./share/man/man4/man4.i386/Makefile:MANSUBDIR=/i386
./share/man/man4/man4.powerpc/Makefile:MANSUBDIR=/powerpc
./usr.sbin/apm/Makefile:MANSUBDIR= /${MACHINE_CPUARCH}
./usr.sbin/apmd/Makefile:MANSUBDIR= /i386
./usr.sbin/nvram/Makefile:MANSUBDIR= /powerpc

or just run: git grep MANSUBDIR=

Things under `man4` are already covered by the patch. Things outside that directory are not.

I'll have a look at it.

> 
> Second, you are aware that you have to patch stable/13 and stable/12 as well? Otherwise the fixes will be not part of our next supported releases.

Well... no. I am not aware of the policy for merging changes like this to stable releases. Would it be necessary/desirable/mandatory? Note I am not a src committer.

stable/13 is the basis for the next release 13.1 If you want a bug fixed in FreeBSD-13.1 RELEASE you need to merge it from -current after some weeks to stable/13. Same for the stable/12 / FreeBSD 12.x

Add man page left overs as reported by wosch@

Harbormaster completed remote builds in B39998: Diff 91135.Jun 20 2021, 12:05 PM

Hi Wolfram,

Thanks for all the input. I think I'm close but I am not familiar with all the makefiles and macros we use in the different *.mk files. For the missing man pages that you mentioned, they are now installed but only in the general directory and not in the arch-specific one.
So for nvram.8, it is installed under /usr/share/man/man8/ but not under /usr/share/man/man8/powerpc

For the manual pages in man4 it was simple to do because we visit the architecture specific makefiles and they just need to be interpreted and executed. But in this case, I don't want to build and install the programs, just the man pages. MLINKS does not create directories, so how can I create the /i386 and /powerpc from the top level directory?

Thanks in advance.

In D30715#693461, @fernape wrote:

Hi Wolfram,

Thanks for all the input. I think I'm close but I am not familiar with all the makefiles and macros we use in the different *.mk files. For the missing man pages that you mentioned, they are now installed but only in the general directory and not in the arch-specific one.
So for nvram.8, it is installed under /usr/share/man/man8/ but not under /usr/share/man/man8/powerpc

For the manual pages in man4 it was simple to do because we visit the architecture specific makefiles and they just need to be interpreted and executed. But in this case, I don't want to build and install the programs, just the man pages. MLINKS does not create directories, so how can I create the /i386 and /powerpc from the top level directory?

I have no idea about the MLINKS stuff and the arch sub-directories. Albeit not being perfect this patch is much better than what we currently have and good enough. Many thanks!.

Note: this patch should be merged 4 weeks later into stable/13 and stable/12, so it will affect the next stable releases.

This revision is now accepted and ready to land.Jun 21 2021, 6:51 AM

In D30715#693653, @wosch wrote:

In D30715#693461, @fernape wrote:

Hi Wolfram,

Thanks for all the input. I think I'm close but I am not familiar with all the makefiles and macros we use in the different *.mk files. For the missing man pages that you mentioned, they are now installed but only in the general directory and not in the arch-specific one.
So for nvram.8, it is installed under /usr/share/man/man8/ but not under /usr/share/man/man8/powerpc

For the manual pages in man4 it was simple to do because we visit the architecture specific makefiles and they just need to be interpreted and executed. But in this case, I don't want to build and install the programs, just the man pages. MLINKS does not create directories, so how can I create the /i386 and /powerpc from the top level directory?

I have no idea about the MLINKS stuff and the arch sub-directories. Albeit not being perfect this patch is much better than what we currently have and good enough. Many thanks!.

Note: this patch should be merged 4 weeks later into stable/13 and stable/12, so it will affect the next stable releases.