Add EXAMPLES section to uname(1)

[danfe]

Summary

I constantly forget which one is which on computers where -m (hardware platform) differs from -p (processor architecture). Add a simple example for 64-bit PowerPC so I don't have to google the answer every time.

[rpokala]

If "platform" (-m) and "processor architecture" (-p) are the same as the TARGET and TARGET_ARCH, then it would be great to include that too.

[imp]

In D10489#217456, @rpokala wrote:

If "platform" (-m) and "processor architecture" (-p) are the same as the TARGET and TARGET_ARCH, then it would be great to include that too.

They are MACHINE and MACHINE_ARCH which are universal, please document them as such. The build man page already gives the translation for the TARGET and TARGET_ARCH which only have meaning in Makefile.inc1 (eg, the top level of buildworld where they are used to set MACHINE and MACHINE_ARCH).

[danfe]

Guys, I don't entirely understand how TARGET/MACHINE and/or TARGET/MACHINE_ARCH come into play here: this patch is about uname(1) only; these variables are not referenced anywhere in its sources, and are partially (?) documented in build(7). Can you elaborate a bit?

[rpokala]

In D10489#217460, @imp wrote:

In D10489#217456, @rpokala wrote:

If "platform" (-m) and "processor architecture" (-p) are the same as the TARGET and TARGET_ARCH, then it would be great to include that too.

They are MACHINE and MACHINE_ARCH which are universal, please document them as such. The build man page already gives the translation for the TARGET and TARGET_ARCH which only have meaning in Makefile.inc1 (eg, the top level of buildworld where they are used to set MACHINE and MACHINE_ARCH).

I see what you're saying. You're right.

In D10489#217461, @danfe wrote:

Guys, I don't entirely understand how TARGET/MACHINE and/or TARGET/MACHINE_ARCH come into play here: this patch is about uname(1) only; these variables are not referenced anywhere in its sources, and are partially (?) documented in build(7). Can you elaborate a bit?

I just wanted to call out the relationship between these two pieces of uname output, and how they're related to what's used for building. But as Warner states, they're really related to MACHINE/MACHINE_ARCH, not TARGET/TARGET_ARCH.

[danfe]

So, shall we proceed with this? Still pending review from manpages...

[imp]

In D10489#217461, @danfe wrote:

Guys, I don't entirely understand how TARGET/MACHINE and/or TARGET/MACHINE_ARCH come into play here: this patch is about uname(1) only; these variables are not referenced anywhere in its sources, and are partially (?) documented in build(7). Can you elaborate a bit?

They are the variables that make(1) sets, based on the values it gets from the same underlying calls that uname gets them from. They are tightly connected in many ways such that many people would refer to uname erroneously when looking for the info in make(1) or build(7). As such, I think having the explicit link mentioned here wouldn't be bad. Strictly speaking, you are correct, but man pages often have references elsewhere, and having it here wouldn't be terrible.

uname.1

110 ↗

(On Diff #27709)

Hardware platform is one of those annoying super-vague phrases. It really means kernel <-> userland API plus some set of base expectations from the hardware.

[danfe]

Strictly speaking, you are correct, but man pages often have references elsewhere, and having it here wouldn't be terrible.

Understood, fair enough. Would .Xr build 7 reference suffice (it already establishes a connection between variables and uname -[mp] output there), or you'd rather duplicate this information explicitly here as well?

uname.1

110 ↗

(On Diff #27709)

This wording comes directly from existing description in this manpage. Do you have better suggestion? In this case we might want to update -m description as well.

[bjk]

uname.1

113 ↗

(On Diff #27709)

manpages grammar alert:

"The hardware platform", "the machine's processor architecture".
(Mostly just adding the "the"s in is the important part.)

[imp]

In D10489#222483, @danfe wrote:

Strictly speaking, you are correct, but man pages often have references elsewhere, and having it here wouldn't be terrible.

Understood, fair enough. Would .Xr build 7 reference suffice (it already establishes a connection between variables and uname -[mp] output there), or you'd rather duplicate this information explicitly here as well?

No. It's a make(1) thing not a build(7) thing for MACHINE and MACHINE_ARCH. TARGET and TARGET_ARCH are a build(7) thing. make(1) doesn't even mention that it automatically sets MACHINE and MACHINE_ARCH from uname -mp (it should). MACHINE and MACHINE_ARCH aren't mentioned at all in build(7) (they should be mentioned as the default values for TARGET and TARGET_ARCH). Build(7) is also wrong: it isn't analogous to uname -m output, it is uname -m output.

Since everybody is passing the buck, no, it isn't OK to just reference them elsewhere unless the elsewhere is actually fixed, correct and complete.

[danfe]

OK, let's see if I understood you correctly this time Warner. make(1) is indeed apparently setting MACHINE and MACHINE_ARCH globally.

[imp]

In D10489#226073, @danfe wrote:

OK, let's see if I understood you correctly this time Warner. make(1) is indeed apparently setting MACHINE and MACHINE_ARCH globally.

Yes.

[danfe]

OK, so I guess we'd need another review from manpages now...

[bjk]

manpages here, just a couple grammar nits.

uname.1

65 ↗

(On Diff #28809)

"set the"

78 ↗

(On Diff #28809)

"set the"

[danfe]

Catch up with the latest review.