forward_decl_audit Namespace Reference

Functions
	count_mentions (path, name)
	layer_of (relpath)
	walk_sources ()
	main ()

Variables
	REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
	SRC = os.path.join(REPO, "src")
	_ig_spec
	_ig = importlib.util.module_from_spec(_ig_spec)
	LAYERS = _ig.LAYERS
	LAYER = _ig.LAYER
	FWD = re.compile(r'^\s*(?:struct|union|enum)\s+([A-Za-z_]\w*)\s*;\s*$')
	DEF_CLOSE = re.compile(r'^\s*\}\s*([A-Za-z_]\w*)\s*;')
	DEF_OPEN = re.compile(r'^\s*(?:typedef\s+)?(?:struct|union|enum)\s+([A-Za-z_]\w*)\s*\{')
	COMMENT_BLOCK = re.compile(r'/\*.*?\*/', re.S)
	COMMENT_LINE = re.compile(r'//[^\n]*')

Detailed Description

Find forward declarations that let a header reach a type from a HIGHER layer.

A forward declaration is normally a good thing: `struct dt_foo_t;` lets a header mention a
type without including the header that defines it, which is how include graphs stay small.
But it also silently defeats the layering check, because there is no #include to count.

`pixel/format.h` was the case that prompted this: it forward-declared `dt_iop_module_t`,
`dt_dev_pixelpipe_t` and `dt_dev_pixelpipe_iop_t` -- three develop/ types, two layers up --
purely so a layer-2 header could declare three functions over them. `tools/include_graph.py`
saw nothing, because nothing was included.

This reports every forward declaration whose type is really defined at a higher layer. Most
findings are legitimate opaque handles: passing a pointer through without touching its
fields costs nothing and creates no real dependency. The ones to look at are where the header
also *declares functions* over the type -- that is the shape that turned out to be an API in
the wrong place.

Usage:
    tools/forward_decl_audit.py [--all] [--json]

--all also lists same-layer and downward forward declarations, which are never a problem.

Function Documentation

count_mentions()

forward_decl_audit.count_mentions	(		path,
			name
	)

Lines mentioning `name` outside comments and outside its own forward declaration.

Definition at line 57 of file forward_decl_audit.py.

Referenced by main().

layer_of()

forward_decl_audit.layer_of

(

relpath

)

Definition at line 70 of file forward_decl_audit.py.

Referenced by main().

main()

forward_decl_audit.main

(

void

)

Definition at line 88 of file forward_decl_audit.py.

References count_mentions(), layer_of(), main(), and walk_sources().

Referenced by main().

walk_sources()

forward_decl_audit.walk_sources

(

)

Definition at line 79 of file forward_decl_audit.py.

Referenced by main().

Variable Documentation

_ig

forward_decl_audit._ig = importlib.util.module_from_spec(_ig_spec)

protected

Definition at line 42 of file forward_decl_audit.py.

_ig_spec

forward_decl_audit._ig_spec

protected

Initial value:

=  importlib.util.spec_from_file_location(
    "_include_graph", os.path.join(os.path.dirname(os.path.abspath(__file__)), "include_graph.py"))

Definition at line 40 of file forward_decl_audit.py.

COMMENT_BLOCK

forward_decl_audit.COMMENT_BLOCK = re.compile(r'/\*.*?\*/', re.S)

Definition at line 53 of file forward_decl_audit.py.

COMMENT_LINE

forward_decl_audit.COMMENT_LINE = re.compile(r'//[^\n]*')

Definition at line 54 of file forward_decl_audit.py.

DEF_CLOSE

forward_decl_audit.DEF_CLOSE = re.compile(r'^\s*\}\s*([A-Za-z_]\w*)\s*;')

Definition at line 49 of file forward_decl_audit.py.

DEF_OPEN

forward_decl_audit.DEF_OPEN = re.compile(r'^\s*(?:typedef\s+)?(?:struct|union|enum)\s+([A-Za-z_]\w*)\s*\{')

Definition at line 50 of file forward_decl_audit.py.

FWD

forward_decl_audit.FWD = re.compile(r'^\s*(?:struct|union|enum)\s+([A-Za-z_]\w*)\s*;\s*$')

Definition at line 47 of file forward_decl_audit.py.

LAYER

forward_decl_audit.LAYER = _ig.LAYER

Definition at line 45 of file forward_decl_audit.py.

LAYERS

forward_decl_audit.LAYERS = _ig.LAYERS

Definition at line 44 of file forward_decl_audit.py.

REPO

forward_decl_audit.REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

Definition at line 32 of file forward_decl_audit.py.

SRC

forward_decl_audit.SRC = os.path.join(REPO, "src")

Definition at line 33 of file forward_decl_audit.py.