Page MenuHomeFreeBSD

Handbook WG - kernelconfig
ClosedPublic

Authored by carlavilla on Apr 26 2023, 7:46 PM.
Tags
None
Referenced Files
Unknown Object (File)
Dec 20 2023, 7:23 AM
Unknown Object (File)
Nov 7 2023, 5:22 PM
Unknown Object (File)
Oct 9 2023, 6:57 AM
Unknown Object (File)
Oct 9 2023, 6:57 AM
Unknown Object (File)
Oct 6 2023, 4:14 PM
Unknown Object (File)
Jun 20 2023, 4:18 PM
Unknown Object (File)
Jun 18 2023, 12:50 AM
Unknown Object (File)
Jun 11 2023, 11:21 AM
Subscribers
None

Details

Summary

Few changes in kernelconfig chapter:

  • Make the first paragraph a note
  • AsciiDoc tweaks
  • Remove stale architectures
  • Remove editors paragraph
  • Add link to config(5)
  • Remove pssection

Preview: https://www.carlavilla.es/freebsd/kernelconfig.html

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

carlavilla created this revision.

I think this chapter is looking good, at least after a quick pass. Just a few comments so far.

documentation/content/en/books/handbook/kernelconfig/_index.adoc
298

These example look strange to me with spaces around the = sign, or at least before it. It is more idiomatic to have the = sign immediately after the variable, although I guess it works this way too. For example, /usr/share/examples/etc/make.conf has no spaces before the =.

357–358

The loader menu can be used to select a kernel without typing it (or remembering it). Just select the Kernel option; each time the option is selected, the name of the next kernel is displayed. The timer is stopped, so you can just press Return when the desired kernel is displayed. I would include this option and not the manual option.

I have a few minor suggestions. Thank you for your work on this!

documentation/content/en/books/handbook/kernelconfig/_index.adoc
191–194

Personally I do not like architecture lists in the docs. Each place we have one is really just an opportunity for it to become stale, so IMO we should avoid such lists when they are not necessary for the text.

208

It should be "MYKERNEL can now..." or "The MYKERNEL file can now...".

258–259

This is good trivia, but LINT is useful only for compile-time testing, and is of no practical use to the audience of this chapter. I think the note can be dropped.

325
334–335

One of the mentions of config could become a link to the man page. Same with make below.

343

This error now (helpfully) includes the filename:

config: /usr/src/sys/amd64/conf/GENERIC:32: syntax error
documentation/content/en/books/handbook/kernelconfig/_index.adoc
267

I would use Move to

325
carlavilla added inline comments.
documentation/content/en/books/handbook/kernelconfig/_index.adoc
298

Really good catch :)

325
357–358

Mike can you please provide the change to improve this paragraph?

carlavilla marked 2 inline comments as done.

Fix almost all the comments :)

documentation/content/en/books/handbook/kernelconfig/_index.adoc
325

Video cards are of course affected by a kernel update, but other ports like virtualbox-ose-kmod, and lsof are also affected by this so maybe this would be a more neutral place. If anything, in the video card section, we could point to this place.

documentation/content/en/books/handbook/kernelconfig/_index.adoc
357–358

This can be accessed when the system boot menu appears by selecting the "Kernel:" option, which initially displays "Kernel: default/kernel".
Each time the option is selected, another choice appears, for example "kernel.old".
When the desired kernel is listed, press return to boot.

357–358

Then remove this line. btw, in the replacement text, is there a better way to quote?

carlavilla added inline comments.
documentation/content/en/books/handbook/kernelconfig/_index.adoc
325

Good idea, let me know if works like that

carlavilla marked an inline comment as done.

One last-minute nit.

documentation/content/en/books/handbook/kernelconfig/_index.adoc
334–335

s/17/32/

documentation/content/en/books/handbook/kernelconfig/_index.adoc
327

Instead of talking about the drm, X and Wayland, I would introduce PORTS_MODULES with something like:

Some ports rely on the kernel sources to build and might malfunction if they were built with a different kernel version.

328

Not all ports that need the sources are drivers.

As such, it is strongly recommended that the drivers... --> As such, it is strongly recommended that these ports...

documentation/content/en/books/handbook/kernelconfig/_index.adoc
327

I think it is useful to give examples so people have an idea what is involved. Maybe generalize a bit, though, e.g. "The Ports Framework includes drivers and other modules that depend on kernel interfaces, such as ..." or something closer to @fernape's suggestion.

documentation/content/en/books/handbook/kernelconfig/_index.adoc
327

I think it is useful to give examples so people have an idea what is involved. Maybe generalize a bit, though, e.g. "The Ports Framework includes drivers and other modules that depend on kernel interfaces, such as ..." or something closer to @fernape's suggestion.

I like it.

carlavilla added inline comments.
documentation/content/en/books/handbook/kernelconfig/_index.adoc
327

What do you think with this last change?

334–335

Nice catch!

carlavilla marked 2 inline comments as done.
documentation/content/en/books/handbook/kernelconfig/_index.adoc
316

is build --> is built.

Also, since we haven't mention PORTS_MODULES yet, I'm not sure about starting with With this variable.... Maybe something like:

With this variable every time the kernel is build,... --> With the PORTS_MODULES variable every time the kernel is built,...

carlavilla marked an inline comment as done.
This revision is now accepted and ready to land.May 8 2023, 7:09 AM
This revision was automatically updated to reflect the committed changes.

Thanks for working on this and sorry for the late feedback.

documentation/content/en/books/handbook/kernelconfig/_index.adoc
109–110

Is this still the preferred location to list kernel modules? I recall suggestions to put, e.g., kld_list="filemon i915kms" in /etc/rc.conf.

189

crossref:mirrors[git,"The source tree can be installed using Git"].

191
246–255

Would it be useful to include a sample lines for nooptions and nodevice.

319
333
350

Review the configuration, and if the problem is not apparent, send an email that includes the kernel configuration file to the {freebsd-questions}.

377

Boot environments are another option for recovering from update failures. I don't see a Handbook section about boot environments, but if we did, it might be useful to add a note with a link here.

documentation/content/en/books/handbook/kernelconfig/_index.adoc
109–110

I think it depends on the module. For modules that are required for hardware initialization, they might better be loaded at an early stage (loader.conf) than later on (rc.conf). But in the general case, especially for *big* modules, they are better off being loaded from /etc/rc.conf. Loading the NVidia driver from loader.conf might leave no room for much else. See this.

246–255

+1

319

+1