Daily doxy­gen gen­er­ated docs of the FreeBSD ker­nel (head)

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­serv­er.

Every night/​morning (Ger­man timezone) the sources will be up­dated, and the docs get re­gen­er­ated (this takes some time). Cur­rently this de­pends upon some patches to the make­file and doxy­gen con­fig files in tools/​kerneldoc/​subsys. Everything is gen­er­ated dir­ectly in the place where the web­serv­er will look for to de­liv­er the pages, so if you browse this in the middle of the gen­er­a­tion, the con­tent may not be con­sist­ent (yet).

Please be nice to the web­serv­er and do not mir­ror this. You can gen­er­ate this your­self very easy. As­sum­ing you have the FreeBSD source on a loc­al hard disk, you just need to down­load the patch from http://​www​.Leidinger​.net/​F​r​e​e​B​S​D​/​c​u​r​r​e​n​t​-​p​a​t​c​h​es/ (if you do not find dox.diff, up­date your FreeBSD sources and everything will be OK), ap­ply the patch, cd in­to tools/​kerneldoc/​subsys and run “make all” (or “make vm” or whatever you are in­ter­ested in). You need doxy­gen in­stalled, off course.

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

In case this is us­ing sig­ni­fic­ant traffic, I will ask core/​ad­mins if there is the pos­sib­il­ity to host it on FreeBSD.org re­sources.

Bikesheds, FC4 and SoC

The last week has seen some bikesheds. One of them was my com­mit of the doxy­gen in­fra­struc­ture for the ker­nel sub­sys­tems. Some people don’t like the way doxy­gen re­quires some markup tags in the com­ments, some people don’t think such API docs provide ad­di­tion­al value and some people fear that 3rd party de­velopers may use some func­tions which shouldn’t be used. I don’t re­peat the counter-​arguments of my­self and oth­er people here, but there are people out there which already make use of the cur­rent un­sat­is­fact­ory doxy­gen out­put and are happy about this in­fra­struc­ture. Luck­ily is was su­per­seeded by an­oth­er bikeshed (and gnn@ wants to work on doc­u­ment­ing a sub­sys­tem to show the be­ne­fits to those people which do not think yet, that this is a good idea). On a re­lated is­sue, I’m wait­ing on a repo copy of src/​sys/​doc to src/​tools (it’s one of two repo cop­ies I’m wait­ing for, ncvs@ seems to be bussy ATM). Some doc@ people think it is more ap­pro­pri­ate there.

The FC4 linux base port and the xorg based linux X11 libs port are sched­uled for test­ing in an ex­per­i­ment­al ports build run, we may see the switch of the de­fault linux base port in the not so dis­tant fu­ture. It seems Bor­is is work­ing on up­dates to the rest of the linuxolat­or in­fra­struc­ture in the Ports Col­lec­tion (gtk, …), so we may see a lot of up­dates there after the switch of the de­fault linux base port.

In the last days I also helped/​talked with my SoC stu­dents. Ro­man is play­ing a little bit with an amd64 tinder­box he got ac­cess to and as a res­ult he com­mit­ted sup­port for build­ing the linuxolat­or on amd64 as a mod­ule to per­force (call for test­ers: he did send a patch to emulation@, please give it a try if you own an amd64 box). Ry­an is cata­loging the IOCTL’s and their status (im­ple­men­ted, ob­sol­ete, …) in the FreeBSD wiki. I already pr­i­or­ized those he did so far, and gave some sug­ges­tions how to pro­ceed with the im­port­ant ones. This way he hasn’t to wait for me or Ar­iff when he is fin­ished with the cata­loging (be­ing a ment­or liv­ing in a dif­fer­ent time zone means you should be ahead of your stu­dent… be­ing ahead even be­fore he is able to asks ques­tions is … a boost for your own ego 😉 ).

The ker­nel sub­sys­tem API doc­u­ment­a­tion gen­er­a­tion frame­work.

I com­mit­ted the ker­nel sub­sys­tem API doc­u­ment­a­tion gen­er­a­tion frame­work. It al­lows to gen­er­ate the API doc­u­ment­a­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 without com­ments and blank lines). Here’s an ex­ample of such a con­fig:

PROJECT_​NAME = “FreeBSD ker­nel sound device code”
EXTRACT_​ALL = YES # for un­doc­u­mented src, no warn­ings en­abled
INPUT = $(DOXYGEN_SRC_PATH)/dev/sound/

GENERATE_​TAGFILE = dev_sound/dev_sound.tag
TAGFILES = dev_pci/dev_pci.tag=../../dev_pci/html \
@INCLUDE = common-​Doxyfile

The frame­work is con­figured 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 oth­er sub­sys­tems are wel­come):

  • cam
  • crypto
  • dev_​pci
  • dev_​sound
  • dev_​usb
  • geom
  • i4b
  • kern
  • lib­kern
  • linux
  • net80211
  • net­graph
  • net­in­et
  • netinet6
  • ne­tipsec
  • open­crypto
  • vm

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