On Thu, Mar 01, 2018 at 11:29:11AM +0100, Ingo Schwarze wrote:
> Jonathan Gray wrote on Thu, Mar 01, 2018 at 07:28:45PM +1100:
> > The binary is installed on all architectures that build llvm as
> > /usr/bin/ld.lld and is also installed as /usr/bin/ld on arm64.
> > With ld.1 from binutils and ld.lld.1 with ld in .Nm 'man ld' will pick
> > the binutils page but the ld.lld.1 page will show up in 'man -a ld' even
> > on architectures where ld is not lld.
> First, all manual pages are supposed to be in distrib/sets/lists/*/mi,
> not in distrib/sets/lists/*/md.*. I know that as.1 and gdb.1 violate
> that, being in comp/md.*, which we should maybe fix, but that's a
> distinct issue. Anyway, making anything manual-page related depend
> on TARGET_ARCH looks somewhat dubious to me.
There are other pages, ie gcc.1 gcov.1 aren't present on arm64.
We don't install gcc3/gcc4 manual pages in architecture specific
directories currently. Or llvm manual pages on architectures
that don't build llvm. And cpp.1 cc.1 c++.1 etc.
> Assuming we want to keep the installation of manual pages mi,
> there are two different issues.
> 1. Which page should man(1) show?
> 2. How should the NAME section look like?
> Regarding question 1, ideally,
> - man ld.lld must always show this new page
> - man -S arm64 ld should show this new page
> - man -S i386 ld should show the GNU ld(1) page
> That would require having these files:
> - /usr/share/man/man1/ld.lld.1
> - /usr/share/man/man1/arm64/ld.1
> - /usr/share/man/man1/i386/ld.1 (different from previous)
> - /usr/share/man/man1/*/ld.1 (same as previous)
> And *not* having this file:
> - /usr/share/man/man1/ld.1
> Regarding question 2, ideally, it would require man1/ld.lld.1 and
> man1/arm64/ld.1 to have different content in the NAME section. But
> that would be a pain to maintain, so i guess we do not want to do
> that. Which means that we do *not* add .Nm ld to NAME in ld.lld.1,
> as a compromise.
> So back to question 1. Getting rid of man1/ld.1 and
> installing the correct man1/*/ld.1 links instead requires
> fiddling with the GNU binutils build system, which seems
> unrelated to this diff. We can decide later whether or not
> we want that.
> For now, i suggest that you import the new file and install
> it as /usr/share/man/man1/ld.lld.1, mi, without the MLINKS
> line in usr.bin/clang/lld/Makefile.
> If you want, you can already install a hard link from
> /usr/share/man/man1/ld.lld.1 to /usr/share/man/man1/arm64/ld.1,
> even though man(1) will not yet show that for "man -S arm64 ls"
> yet as long as man1/ld.1 exists (mi pages are preferred even
> with -S). But at least it will already show up in "man -aS arm64 ld"
> and in "man -w ld".
This diff was prompted by arm64 checkflist showing a missing file
for ld.1 on arm64. While I agree the ideal case would have the pages
moved to md directories for the conflicting pages none of the toolchain
pages seem to do that at the moment.