I man­aged to get some time to setup an auto­mated gen­er­a­tion of the doxy­gen docs for ker­nel sub­sys­tems of FreeBSD on my web­server.

Every night/morning (Ger­man time­zone) the sources will be updated, and the docs get regen­er­ated (this takes some time). Cur­rently this depends upon some patches to the make­file and doxy­gen con­fig files in tools/kerneldoc/subsys. Every­thing is gen­er­ated directly in the place where the web­server will look for to deliver the pages, so if you browse this in the mid­dle of the gen­er­a­tion, the con­tent may not be con­sis­tent (yet).

Please be nice to the web­server and do not mir­ror this. You can gen­er­ate this your­self very easy. Assum­ing you have the FreeBSD source on a local hard disk, you just need to down­load the patch from http://www.Leidinger.net/FreeBSD/current-patches/ (if you do not find dox.diff, update your FreeBSD sources and every­thing will be OK), apply the patch, cd into tools/kerneldoc/subsys and run “make all” (or “make vm” or what­ever you are inter­ested in). You need doxy­gen installed, off course.

If you want to setup some­thing like this your­self, just down­load the script which is doing all the work, change some vari­ables in the begin­ning, and cre­ate your own local ver­sion of the com­plete docs.

In case this is using sig­nif­i­cant traf­fic, I will ask core/admins if there is the pos­si­bil­ity to host it on FreeBSD.org resources.

The last week has seen some bikesheds. One of them was my com­mit of the doxy­gen infra­struc­ture for the ker­nel sub­sys­tems. Some peo­ple don’t like the way doxy­gen requires some markup tags in the com­ments, some peo­ple don’t think such API docs pro­vide addi­tional value and some peo­ple fear that 3^rd party devel­op­ers may use some func­tions which shouldn’t be used. I don’t repeat the counter-arguments of myself and other peo­ple here, but there are peo­ple out there which already make use of the cur­rent unsat­is­fac­tory doxy­gen out­put and are happy about this infra­struc­ture. Luck­ily is was super­seeded by another bikeshed (and gnn@ wants to work on doc­u­ment­ing a sub­sys­tem to show the ben­e­fits to those peo­ple which do not think yet, that this is a good idea). On a related issue, I’m wait­ing on a repo copy of src/sys/doc to src/tools (it’s one of two repo copies I’m wait­ing for, ncvs@ seems to be bussy ATM). Some doc@ peo­ple think it is more appro­pri­ate there.

The FC4 linux base port and the xorg based linux X11 libs port are sched­uled for test­ing in an exper­i­men­tal ports build run, we may see the switch of the default linux base port in the not so dis­tant future. It seems Boris is work­ing on updates to the rest of the lin­ux­o­la­tor infra­struc­ture in the Ports Col­lec­tion (gtk, …), so we may see a lot of updates there after the switch of the default linux base port.

In the last days I also helped/talked with my SoC stu­dents. Roman is play­ing a lit­tle bit with an amd64 tin­der­box he got access to and as a result he com­mit­ted sup­port for build­ing the lin­ux­o­la­tor on amd64 as a mod­ule to per­force (call for testers: he did send a patch to emulation@, please give it a try if you own an amd64 box). Ryan is cat­a­loging the IOCTL’s and their sta­tus (imple­mented, obso­lete, …) in the FreeBSD wiki. I already pri­or­ized those he did so far, and gave some sug­ges­tions how to pro­ceed with the impor­tant ones. This way he hasn’t to wait for me or Ariff when he is fin­ished with the cat­a­loging (being a men­tor liv­ing in a dif­fer­ent time zone means you should be ahead of your stu­dent… being ahead even before he is able to asks ques­tions is … a boost for your own ego ).

I com­mit­ted the ker­nel sub­sys­tem API doc­u­men­ta­tion gen­er­a­tion frame­work. It allows to gen­er­ate the API doc­u­men­ta­tion of a sub­sys­tem (with doxy­gen) just by adding a short con­fig file (around 22 lines with com­ments and blank lines, maybe 14 lines with­out com­ments and blank lines). Here’s an exam­ple of such a config:

—snip—
PROJECT_NAME = “FreeBSD ker­nel sound device code“
OUTPUT_DIRECTORY = $(DOXYGEN_DEST_PATH)/dev_sound/
EXTRACT_ALL = YES # for undoc­u­mented src, no warn­ings enabled
INPUT = $(DOXYGEN_SRC_PATH)/dev/sound/

GENERATE_TAGFILE = dev_sound/dev_sound.tag
TAGFILES = dev_pci/dev_pci.tag=../../dev_pci/html
dev_usb/dev_usb.tag=../../dev_usb/html
@INCLUDE_PATH = $(DOXYGEN_INCLUDE_PATH)
@INCLUDE = common-Doxyfile
—snip—

The frame­work is con­fig­ured to not only gen­er­ate the HTML ver­sion, but also a PDF ver­sion.

Sub­sys­tems for which docs are gen­er­ated cur­rently (con­figs for other sub­sys­tems are welcome):

• cam
• crypto
• dev_pci
• dev_sound
• dev_usb
• geom
• i4b
• kern
• libkern
• linux
• net80211
• net­graph
• netinet
• netinet6
• netipsec
• open­crypto
• vm

Peo­ple which want to help doc­u­ment­ing the code may want to have a look at the spe­cial com­mands doxy­gen under­stands.