More dri­vers avail­able in the FreeBSD-kernel doxy­gen docs

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­cal­ly gen­er­at­ed miss­ing con­figs for sub­di­rec­to­ries of src/sys/dev/. This means there is no depen­den­cy infor­ma­tion includ­ed 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­cal­ly gen­er­at­ed infor­ma­tion.

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­i­ty), name­ly:

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

Send to Kin­dle

Direct, indi­rect and explic­it depen­den­cies in progams/ports

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

Some def­i­n­i­tions:

  • A direct depen­den­cy from A to B is when program/port A uses sym­bols from library/port B.
  • An indi­rect depen­den­cy 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 explic­it depen­den­cy from A to C is when it is a direct or indi­rect depen­den­cy A to C, and when the compiler-time-link­er added an explic­it ref­er­ence to C to the program/lib of A.

Ide­al­ly we have no indi­rect depen­den­cies in the explic­it depen­den­cies, only direct depen­den­cies. Unfor­tu­nate­ly in real­i­ty we also have indi­rect depen­den­cies there. This has at least two caus­es:

  1. libtool (at least 1.x) does not (or was not) come with a hint on FreeB­SD, which tells that the run-time-linker is recur­sive­ly resolv­ing depen­den­cies.
  2. Some pkg-con­fig setups list indi­rect depen­den­cies as explic­it 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­den­cy appear from this soft­ware, but I am not 100% sure about this).

Three years ago I wrote /usr/ports/Tools/scripts/, it looks at the files of a giv­en port (it needs to be installed), and prints out explic­it depen­den­cies. Because of the indi­rect depen­den­cies which could be list­ed 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­i­ty. 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.

Send to Kin­dle

Ports relat­ed stuff

The pack­age depen­den­cy speedup was com­mit­ted by port­m­gr, unfor­tu­nate­ly 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­i­ty to switch of the reg­is­tra­tion of implic­it 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­den­cy changes).

Patch­es 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 low­er than the infra­struc­ture pro­cess­ing (I doubt you will see a sig­nif­i­cant change in a build of OO 😉 ).

Send to Kin­dle