build/development.7: System building examples

[ziaee]

Summary

build/development.7: System building examples

The system reference 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), and build(7), they
needed some work, and I thought it was better to work on them together.

build(7):
+ refactor introduction for presentation
+ EXAMPLES: explain build(7)ing the system
+ CAVEATS: import common cases from src/UPDATING
+ BUGS: instructions for build(7)ing the system are proliferated
+ fix some weird line wrapping/indentation

development(7):
- system build(7)ing examples moved to build(7)
+ mention github
+ add examples for applying patches

MFC after:              3 days
Reported by:            emaste (manpages needs a kernconf example)
Reported by:            imp (kernconfs include and go from there)
Differential Revision:  https://reviews.freebsd.org/D48693

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.

[ziaee]

In D48693#1110685, @imp wrote:

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.

Yes, I think that's exactly it. git-arc just lost a revision upon correcting the commit message title from "ports.7/history: Don't forget MacOS" to "ports.7/history: Don't forget macOS". After editing the commit title through the Phabricator web interface, git-arc was able to find and update it again.