include_report Namespace Reference

Functions
	build ()
	closures (files, graph)
	bar_chart (rows, title, unit, colour=PALETTE[0], width=900, row_h=22)
	matrix (viol, width=900)
	main ()

Variables
list	PALETTE = ['#4c8bf5', '#e8710a', '#12a37a', '#c5221f', '#a142f4', '#f9ab00']

Detailed Description

Aggregate include-hygiene report: a single self-contained HTML page with SVG charts.

This deliberately does NOT draw per-file include graphs -- doc/Doxyfile already has
HAVE_DOT with INCLUDE_GRAPH, INCLUDED_BY_GRAPH and DIRECTORY_GRAPH, and produces
interactive SVG that is better for drilling into one file than anything here.

What Doxygen does not give you, and this does:
  * RANKING   -- which headers cost the most, sorted, with numbers you can diff
  * BLAST RADIUS -- how many TUs recompile when header X is touched, quantified
  * LAYERING  -- inversions counted per directory pair, not just drawn
  * TREND     -- the same metrics at two git revisions, side by side
  * UNUSED    -- candidate removable includes (see tools/include_unused.py)

Note on the Doxygen graphs: DOT_GRAPH_MAX_NODES is 100 in doc/Doxyfile, so exactly the
god-headers worth looking at render truncated. Raise it (or set MAX_DOT_GRAPH_DEPTH)
before drilling into one of the headers this report ranks at the top.

No third-party dependencies: charts are hand-emitted SVG so the tool runs anywhere the
rest of tools/ runs, including CI.

Usage:
  python3 tools/include_report.py                        # writes include-report.html
  python3 tools/include_report.py -o /tmp/r.html
  python3 tools/include_report.py --unused unused.json   # fold in include_unused.py --json

Function Documentation

bar_chart()

include_report.bar_chart	(		rows,
			title,
			unit,
			colour = PALETTE[0],
			width = 900,
			row_h = 22
	)

rows: list of (label, value). Emits a horizontal bar chart as inline SVG.

Definition at line 68 of file include_report.py.

References max.

Referenced by main().

build()

include_report.build

(

)

Definition at line 38 of file include_report.py.

Referenced by main().

closures()

include_report.closures	(		files,
			graph
	)

Definition at line 50 of file include_report.py.

Referenced by main().

main()

include_report.main

(

void

)

Definition at line 109 of file include_report.py.

References bar_chart(), build(), closures(), and main().

Referenced by main().

matrix()

include_report.matrix	(		viol,
			width = 900
	)

Directory-pair inversion counts as a heat table.

Definition at line 92 of file include_report.py.

Variable Documentation

PALETTE

list include_report.PALETTE = ['#4c8bf5', '#e8710a', '#12a37a', '#c5221f', '#a142f4', '#f9ab00']

Definition at line 35 of file include_report.py.