Yes­ter­day I com­mit­ted some more con­figs to gen­er­ate doxy­gen doc­u­men­ta­tion of FreeBSD-kernel dri­vers. I mechan­i­cally gen­er­ated miss­ing con­figs for sub­di­rec­to­ries of src/sys/dev/. This means there is no depen­dency infor­ma­tion included in the con­figs, and as such you will not get links e.g. to the PCI doc­u­men­ta­tion, if a dri­ver calls func­tions in the PCI dri­ver (feel free to tell me about such depen­den­cies).

If  you want to gen­er­ate the HTML or PDF ver­sion of some sub­sys­tem, just go to src/tools/kerneldoc/subsys/ an run “make” to get a list of tar­gets to build. As an exam­ple, “make dev_sound” will gen­er­ate the HTML ver­sion for the sound sys­tem, “make pdf-dev_sound” gen­er­ates the PDF ver­sion. The sound sys­tem is prob­a­bly the most “nice” exam­ple, as it includes a page with TODO items, and has even some real API docs instead of just the call-graphs and such auto­mat­i­cally gen­er­ated information.

Some dri­vers already have (some) doxy­gen markup (I did just a quick grep for ‘/*[*!]’ to detect doxy­gen markup indi­ca­tors, no idea about the cov­er­age or qual­ity), namely:

• agp
• ath
• bktr
• bxe
• cxgb
• cxgbe
• dpt
• drm
• e1000
• iir
• ixgbe
• mwl
• nxge
• ofw
• pccard
• siba
• wpi
• xen

There is more doc­u­men­ta­tion than only for those dri­vers, I just listed those as there are at least parts of doxy­gen doc­u­men­ta­tion inside.

The dis­cus­sion about direct and indi­rect depen­den­cies is com­ing up again on the FreeBSD mail­inglists. Seems I should make some blog post about it, maybe it makes this topic more find­able than my post­ings in the mailinglists.

Some def­i­n­i­tions:

• A direct depen­dency from A to B is when program/port A uses sym­bols from library/port B.
• An indi­rect depen­dency from A to C is when program/port A uses sym­bols from library/port B but no sym­bols from library/port C, and library/port B uses sym­bols from library/port C.
• An explicit depen­dency from A to C is when it is a direct or indi­rect depen­dency A to C, and when the compiler-time-linker added an explicit ref­er­ence to C to the program/lib of A.

Ide­ally we have no indi­rect depen­den­cies in the explicit depen­den­cies, only direct depen­den­cies. Unfor­tu­nately in real­ity we also have indi­rect depen­den­cies there. This has at least two causes:

1. libtool (at least 1.x) does not (or was not) come with a hint on FreeBSD, which tells that the run-time-linker is recur­sively resolv­ing dependencies.
2. Some pkg-config setups list indi­rect depen­den­cies as explicit depen­den­cies (IIRC it depends if Requires.private and/or Libs.private is used in the .pc file or not; if it is used, there should be no indi­rect depen­dency appear from this soft­ware, but I am not 100% sure about this).

Three years ago I wrote /usr/ports/Tools/scripts/explicit_lib_depends.sh, it looks at the files of a given port (it needs to be installed), and prints out explicit depen­den­cies. Because of the indi­rect depen­den­cies which could be listed there, this list is not a list of ports which are real depen­den­cies from a source code point of view, but it reflects the link–time real­ity. If a port C shows up there, the port which is checked needs to be rebuild in case the ABI of library/port C changes.

The pack­age depen­dency speedup was com­mit­ted by port­mgr, unfor­tu­nately it was not the lat­est ver­sion of it. The most recent ver­sion is sched­uled for an exper­i­men­tal ports build run (my patch also con­tains the pos­si­bil­ity to switch of the reg­is­tra­tion of implicit depen­den­cies, if enabled it gives a much bet­ter pic­ture regard­ing which port needs to be rebuild (portre­vi­sion bump) in case a depen­dency changes).

Patches for speed­ing up “make clean” are also sched­uled for an exper­i­men­tal ports build run. The pkg_create patch was also com­mit­ted to -cur­rent.

With all those stuff an update is much faster now, at least for those ports where the compile/build time was much lower than the infra­struc­ture pro­cess­ing (I doubt you will see a sig­nif­i­cant change in a build of OO ).