More drivers 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­ment­a­tion of FreeBSD-​kernel drivers. I mech­an­ic­ally gen­er­ated miss­ing con­figs for sub­dir­ect­or­ies of src/​sys/​dev/​. This means there is no de­pend­ency in­form­a­tion in­cluded in the con­figs, and as such you will not get links e.g. to the PCI doc­u­ment­a­tion, if a driver calls func­tions in the PCI driver (feel free to tell me about such de­pend­en­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 ex­ample, “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­ably the most “nice” ex­ample, as it in­cludes a page with TODO items, and has even some real API docs in­stead of just the call-​graphs and such auto­mat­ic­ally gen­er­ated in­form­a­tion.

Some drivers already have (some) doxy­gen markup (I did just a quick grep for „/​*[*!]“ to de­tect doxy­gen markup in­dic­at­ors, no idea about the cov­er­age or qual­ity), namely:

There is more doc­u­ment­a­tion than only for those drivers, I just lis­ted those as there are at least parts of doxy­gen doc­u­ment­a­tion in­side.

Dir­ect, in­dir­ect and ex­pli­cit de­pend­en­cies in progams/​ports

The dis­cus­sion about dir­ect and in­dir­ect de­pend­en­cies is com­ing up again on the FreeBSD mailing­lists. Seems I should make some blog post about it, may­be it makes this top­ic more find­able than my post­ings in the mailing­lists.

Some defin­i­tions:

  • A dir­ect de­pend­ency from A to B is when program/​port A uses sym­bols from library/​port B.
  • An in­dir­ect de­pend­ency 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 ex­pli­cit de­pend­ency from A to C is when it is a dir­ect or in­dir­ect de­pend­ency A to C, and when the compiler-​time–linker ad­ded an ex­pli­cit ref­er­ence to C to the program/​lib of A.

Ideally we have no in­dir­ect de­pend­en­cies in the ex­pli­cit de­pend­en­cies, only dir­ect de­pend­en­cies. Un­for­tu­nately in real­ity we also have in­dir­ect de­pend­en­cies there. This has at least two causes:

  1. lib­tool (at least 1.x) does not (or was not) come with a hint on FreeBSD, which tells that the run-​time-​linker is re­curs­ively resolv­ing de­pend­en­cies.
  2. Some pkg–con­fig setups list in­dir­ect de­pend­en­cies as ex­pli­cit de­pend­en­cies (IIRC it de­pends if Requires.private and/​or Libs.private is used in the .pc file or not; if it is used, there should be no in­dir­ect de­pend­ency ap­pear from this soft­ware, but I am not 100% sure about this).

Three years ago I wro­te /​usr/​ports/​Tools/​scripts/, it looks at the files of a given port (it needs to be in­stalled), and prints out ex­pli­cit de­pend­en­cies. Be­cause of the in­dir­ect de­pend­en­cies which could be lis­ted there, this list is not a list of ports which are real de­pend­en­cies from a source code point of view, but it re­flects the link-​time real­ity. If a port C shows up there, the port which is checked needs to be re­build in case the ABI of library/​port C changes.

Ports re­lated stuff

The pack­age de­pend­ency spee­dup was com­mit­ted by port­m­gr, un­for­tu­nately it was not the latest ver­sion of it. The most re­cent ver­sion is sched­uled for an ex­per­i­ment­al ports build run (my patch also con­tains the pos­sib­il­ity to switch of the re­gis­tra­tion of im­pli­cit de­pend­en­cies, if en­abled it gives a much bet­ter pic­ture re­gard­ing which port needs to be re­build (port­re­vi­sion bump) in case a de­pend­ency changes).

Patches for speed­ing up “make clean” are also sched­uled for an ex­per­i­ment­al ports build run. The pkg_​create patch was also com­mit­ted to -cur­rent.

With all those stuff an up­date is much faster now, at least for those ports where the compile/​build time was much lower than the in­fra­struc­ture pro­cessing (I doubt you will see a sig­ni­fic­ant change in a build of OO 😉 ).