build/development.7: System building examples

[ziaee]

Summary

build/development.7: System building examples

The manual is notably missing building a custom kernel. To polish the
idea of a complete, well-integrated system, the integrated doc could
use this. Upon reviewing development(7), the description says that
"build instructions can be found in build(7)", which makes a lot of
sense to me.

Therefore, move all of these examples on building the system to build(7)
and bring the instructions up to date with src/UPDATING. Provide a new
example for building a custom kernel.

While here, give build(7)/FILES some love, and the example for
PORTS_MODULES was indented far enough to wrap on std. console. Set that
back to increase legibility.

Outstanding:
- development(7) needs a section on github
- it could probably u ]]se subsections
- build(7) has potentially confusing language in the introduction

MFC after:              3 days
Reported by:            emaste (manpages needs a kernconf example)
Reported by:            imp (kernconfs include and go from there)

Test Plan

# apply patch
sh src/tools/tools/git/git-arc.sh patch D48693
# look at rendered manual on various consoles, consider split screen with existing
MANWIDTH=80 man share/man/man 7/development.7
MANWIDTH=59 man share/man/man 7/development.7
# evaluate for accuracy, consistency, location, flow, style, tenseness, omission
# test examples
# lint manual
mandoc -Tlint share/man/man 7/development.7

(I'm trying to flesh manage testing procedure out to eventually become a doc or something)

[imp]

Not copy.

We recommend using include with either device or nodevice to include or exclude devices.. ditto for option and nooption

[ziaee]

The description says build examples are in build(7) and release(7).
I think build(7) is a very sensible place for them, and I would like to
move this entire section there.

[ziaee]

Here's what I've got so far. I don't have any working non-amd64 devices to test many of these options on.

When testing this I discovered, interestingly enough, the kernel won't build with just nodevice sound, and I loose trackpad support in X on MINIMAL.

[ziaee]

Oops, I forgot to make the patch with -U9999 like bz taught me.
That, is an excellent example which I think is very appropriate to put in development(7).

[christos]

In D48693#1110642, @ziaee wrote:

Oops, I forgot to make the patch with -U9999 like bz taught me.
That, is an excellent example which I think is very appropriate to put in development(7).

You can also use git-arc(1) to avoid the manual diffing. John Baldwin has written an article on using it: https://freebsdfoundation.org/wp-content/uploads/2021/11/FreeBSD-Code-Review-with-git-arc.pdf

[ziaee]

Thanks! That's how I create them, but this one changed too much for git-arc.sh update HEAD.

[christos]

In D48693#1110663, @ziaee wrote:

Thanks! That's how I create them, but this one changed too much for git-arc.sh update HEAD.

Does this mean the patch doesn't apply cleanly on main?

[ziaee]

No, I don't understand exactly what it does, but if the commit changes too much, git arc can't update it. You can apply it with git-arc.sh patch D48693.

[imp]

In D48693#1110677, @ziaee wrote:

No, I don't understand exactly what it does, but if the commit changes too much, git arc can't update it. You can apply it with git-arc.sh patch D48693.

I'm sure jhb and i would be interested in a test case.

More likely your first line of the commit messasge.