Yesterday I committed some more configs to generate doxygen documentation of FreeBSD-kernel drivers. I mechanically generated missing configs for subdirectories of src/sys/dev/. This means there is no dependency information included in the configs, and as such you will not get links e.g. to the PCI documentation, if a driver calls functions in the PCI driver (feel free to tell me about such dependencies).
If you want to generate the HTML or PDF version of some subsystem, just go to src/tools/kerneldoc/subsys/ an run “make” to get a list of targets to build. As an example, “make dev_sound” will generate the HTML version for the sound system, “make pdf-dev_sound” generates the PDF version. The sound system is probably the most “nice” example, as it includes a page with TODO items, and has even some real API docs instead of just the call-graphs and such automatically generated information.
Some drivers already have (some) doxygen markup (I did just a quick grep for ‘/*[*!]’ to detect doxygen markup indicators, no idea about the coverage or quality), namely:
There is more documentation than only for those drivers, I just listed those as there are at least parts of doxygen documentation inside.
The discussion about direct and indirect dependencies is coming up again on the FreeBSD mailinglists. Seems I should make some blog post about it, maybe it makes this topic more findable than my postings in the mailinglists.
- A direct dependency from A to B is when program/port A uses symbols from library/port B.
- An indirect dependency from A to C is when program/port A uses symbols from library/port B but no symbols from library/port C, and library/port B uses symbols from library/port C.
- An explicit dependency from A to C is when it is a direct or indirect dependency A to C, and when the compiler-time-linker added an explicit reference to C to the program/lib of A.
Ideally we have no indirect dependencies in the explicit dependencies, only direct dependencies. Unfortunately in reality we also have indirect dependencies there. This has at least two causes:
- libtool (at least 1.x) does not (or was not) come with a hint on FreeBSD, which tells that the run-time-linker is recursively resolving dependencies.
- Some pkg-config setups list indirect dependencies as explicit dependencies (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 indirect dependency appear from this software, 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 dependencies. Because of the indirect dependencies which could be listed there, this list is not a list of ports which are real dependencies from a source code point of view, but it reflects the link-time reality. 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 package dependency speedup was committed by portmgr, unfortunately it was not the latest version of it. The most recent version is scheduled for an experimental ports build run (my patch also contains the possibility to switch of the registration of implicit dependencies, if enabled it gives a much better picture regarding which port needs to be rebuild (portrevision bump) in case a dependency changes).
Patches for speeding up “make clean” are also scheduled for an experimental ports build run. The pkg_create patch was also committed to -current.
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 infrastructure processing (I doubt you will see a significant change in a build of OO 😉 ).