config.5: Document CONF_CFLAGS under 'makeoptions'

[olce]

Summary

This variable serves to tweak CFLAGS from the kernel configuration file,
easing some custom kernel builds. It was introduced by bde@ in 1999.

[olce]

Oops, sorry, I inadvertently committed this along with something else... Re-opening.

[markj]

usr.sbin/config/config.5

330

Can it just be "They are appended after .Va CFLAGS , ..."?

[olce]

usr.sbin/config/config.5

330

Could be, but that wouldn't be completely true and a bit in contradiction with the rest of the sentence.

Something like "They are aggregated into the final CFLAGS in a way that allows overriding what is not essential to the build process"?

[markj]

usr.sbin/config/config.5

330

Sorry, but I just find that confusing: what is "aggregated" in this context? What is "essential"? If I read that I would have to go to the source to understand what actually happens.

I'd just write something like, "They are appended to the existing compiler flags, allowing those flags to be overridden." That's certainly the intent of the variable.

[imp]

usr.sbin/config/config.5

330

Do we want to make it clearer that they are appended as the very last override?

When defined
via
.Ic makeoptions ,
the value of
.Va CONF_FLAGS
is appended to
.Va CFLAGS
allowing default options in CFLAGS to be overridden.

[imp]

usr.sbin/config/config.5

330

or maybe "overridden or augmented."

[olce]

usr.sbin/config/config.5

330

(snip) what is "aggregated" in this context?

The "custom compiler flags" of the previous sentence.

What is "essential"?

Flags without which the build will fail. I've been intentionally vague on that part (users that need to know will have to look at the makefiles).

If I read that I would have to go to the source to understand what actually happens.

I'm trying to find a formulation conveying that, in general, users can pass any flag and that will work as expected, but in exotic cases some might be ignored.

(snip) That's certainly the intent of the variable.

It's the intent yes, and in general what happens, but not what always happens. Maybe you're finding it as too much nuance to keep it here, but I'd prefer to find a way to convey it, so that users are not surprised in corner cases.

330

Another try (replaces only the last sentence "They are appended after most (...) that are not essential to the build process"):

They will generally override those put into CFLAGS by the common makefiles, except for those flags that are required for the build to succeed.

[markj]

usr.sbin/config/config.5

330

The build infrastructure doesn't know anything about overriding or essential flags. It's just appending one variable to another. If you override something incorrectly, the build will fail or give you something unexpected.

I think it can be assumed that someone who wants to tweak the compiler flags of their kernel build already understands this, which is why I prefer to keep it simple and just document that CONF_CFLAGS is appended to the compiler flags, i.e., Warner's suggestion. Whatever happens after that is up to the compiler.

But ok, I don't object to any particular wording.

[olce]

I've rephrased following your advices, mentioning potential exceptions only in the commit message.