include_graph Namespace Reference

Functions
	layer_of (path)
	collect ()
	resolve (inc, from_path, known)
	tarjan (graph, nodes)
	main ()
	what_if (files, graph)
	summary (files, graph, headers, closure, comps, viol)
	mermaid (graph, viol_pairs)

Variables
str	SRC = 'src'
	INCLUDE_RE = re.compile(r'^\s*#\s*include\s+"([^"]+)"', re.M)
list	LAYERS
	LAYER = dict(LAYERS)

Detailed Description

Static analysis of the project's #include graph.

Run from the repository root:  python3 tools/include_graph.py

Builds the DIRECT include graph from source (project includes only), then reports:
  1. cycles (strongly connected components > 1) -- these are exactly what #pragma once
     hides; the guards can only be removed once this section reports none;
  2. layering violations against the declared layer order below;
  3. god-headers by transitive fan-in (how many files rebuild when you touch it);
  4. headers with the largest transitive closure (what including one costs).

It reads sources, not the build, so it needs no compilation and covers every
configuration at once -- including the #ifdef branches your own build does not take.
The trade-off is that it counts includes inside conditional blocks unconditionally.
For a single translation unit's REAL expansion, use the compiler instead:
    gcc -H -fsyntax-only <flags from build/compile_commands.json> file.c
and for unused includes, clang-include-cleaner or include-what-you-use.

Function Documentation

collect()

include_graph.collect

(

)

Definition at line 72 of file include_graph.py.

Referenced by main().

layer_of()

include_graph.layer_of

(

path

)

Definition at line 62 of file include_graph.py.

Referenced by main().

main()

include_graph.main

(

void

)

Definition at line 133 of file include_graph.py.

References collect(), layer_of(), mermaid(), resolve(), summary(), tarjan(), and what_if().

Referenced by mermaid().

mermaid()

include_graph.mermaid	(		graph,
			viol_pairs
	)

Directory-level aggregate, renderable inline in a GitHub comment.

Definition at line 309 of file include_graph.py.

References main().

Referenced by main().

resolve()

include_graph.resolve	(		inc,
			from_path,
			known
	)

Definition at line 89 of file include_graph.py.

Referenced by main().

summary()

include_graph.summary	(		files,
			graph,
			headers,
			closure,
			comps,
			viol
	)

One-line-per-metric output, for before/after comparison.

Definition at line 259 of file include_graph.py.

Referenced by main().

tarjan()

include_graph.tarjan	(		graph,
			nodes
	)

Definition at line 99 of file include_graph.py.

References min.

Referenced by main().

what_if()

include_graph.what_if	(		files,
			graph
	)

Re-count layering violations as if some files lived elsewhere.

Relocation is cheap to do and expensive to undo, and intuition is unreliable here:
moving the history/* cluster into develop/ LOOKS obviously right (it calls
dt_dev_* constantly) and measures at +15 violations, because its own consumers sit
below develop/. Simulate first.

Usage:  --what-if src/common/foo.c=develop src/common/foo.h=develop

Definition at line 213 of file include_graph.py.

Referenced by main().

Variable Documentation

INCLUDE_RE

include_graph.INCLUDE_RE = re.compile(r'^\s*#\s*include\s+"([^"]+)"', re.M)

Definition at line 24 of file include_graph.py.

LAYER

include_graph.LAYER = dict(LAYERS)

Definition at line 60 of file include_graph.py.

LAYERS

list include_graph.LAYERS

Definition at line 29 of file include_graph.py.

SRC

str include_graph.SRC = 'src'

Definition at line 23 of file include_graph.py.