Running doxygen

You'll need to grab a couple debian packages to make this work. The ones I used were:

Doxygen probably also requires a bunch of other stuff to be around, I use a 'standard run environment' which is populated with the superset of utilities needed by everything in my build (rather than figuring out the minimal orthogonal subset for each tool), so my run environment already has things like bash, tcsh, sed, grep, gzip, tar, texinfo, etc--it wouldn't surprise me if doxygen required some of these utilities around to run correctly.

Anyway, once you have an environment that doxygen can run in, then the strategy is pretty straightforward. For any C/C++ source tree you'd like to doxygen, first evaluate it like this: 

. ++= [Cxx = [options  = [return_sources = TRUE]]] ++
      [C   = [options  = [return_sources = TRUE]]]
foo_tree = ./Cxx/program("foo", <sources & libs>);

Then you want to pass this binding to the run_doxygen function below (or something similar): 

  /**nocache**/
  run_doxygen(b: binding): binding
  {
    . ++= [root = ./run_env/root];
    . ++= [root/.WD = b];

    . ++= [root/.WD/Doxyfile = "RECURSIVE              = YES\n"+
                               "GENERATE_LATEX         = NO\n"+
                               "EXCLUDE_PATTERNS       = */libc/*\n"];

    cmd = <"/usr/bin/doxygen", "Doxyfile">;

    . ++= [tool_dep_control/pk = [.WD = TRUE]];
    r =  _run_tool(./target_platform, cmd,
                /*stdin=*/ "",
                /*stdout_treatment=*/ "report_value",
                /*stderr_treatment=*/ "report_value",
                /*status_treatment=*/ "report_nocache",
                /*signal_treatment=*/ "report_nocache",
                /*fp_content=*/ -2,
                /*wd=*/ ".WD",
                /*existing_writable=*/ FALSE);

    return [doxygen = r/root/.WD];
  };

The return value of the function will include the html tree of generated documentation. You can change doxygen options by controlling the text assigned to Doxyfile within the function. For gigantic external libraries that you don't want to doxygen, add something to EXCLUDE_PATTERNS (like I did with libc).

NOTE: it technically isn't necessary to build the executable in order to run doxygen, but that serves two purposes. One, we can use the c_like bridge to gather all the necessary sources for us (including libraries and sources that may be have been generated by other tool steps), and secondly we can make sure that the source tree actually builds--otherwise we might chase down doxygen errors that are really related to a build problem.

You probably don't want to run this by default in your normal build--it runs slowly for large builds.