symbol_coupling Namespace Reference

Functions
	module_of (obj_path)
	nm (obj, args)
	collect (build)
	edges (owner, undef)
	main ()

Variables
dict	LAYER
	OBJ_RE = re.compile(r'\.dir/(.*)\.(?:c|cc|cpp)\.o$')

Detailed Description

Module coupling measured at the SYMBOL level, from the linker's point of view.

tools/include_graph.py measures what a file *reads* -- textual `#include` edges. This
measures what actually *links*: for every compiled object, which symbols it defines and
which it leaves undefined, resolved against the module that defines them. The result is
the real API surface between subsystems.

Why it is worth having both: an include edge can be an accident (a header pulled in for
one typedef), and removing it changes nothing about the program. A symbol edge is a call
that exists at runtime. When `include_graph.py` reports `common/ -> control/ : 104`, this
tool answers the question that actually matters for modularisation -- WHICH functions,
so the inversion becomes a work list rather than a number.

Reads .o files from the build directory, so it needs a completed build and reflects the
configuration that produced it (a `nofeatures` build will show fewer edges).

Usage:
  python3 tools/symbol_coupling.py                     # module x module summary
  python3 tools/symbol_coupling.py --edge common develop   # the symbols behind one edge
  python3 tools/symbol_coupling.py --inversions        # only upward edges (layer breaks)
  python3 tools/symbol_coupling.py --build build-nofeatures

Function Documentation

collect()

symbol_coupling.collect

(

build

)

Definition at line 56 of file symbol_coupling.py.

References module_of(), and nm().

Referenced by main().

edges()

symbol_coupling.edges	(		owner,
			undef
	)

Definition at line 75 of file symbol_coupling.py.

Referenced by main().

main()

symbol_coupling.main

(

void

)

Definition at line 85 of file symbol_coupling.py.

References collect(), edges(), and main().

Referenced by main().

module_of()

symbol_coupling.module_of

(

obj_path

)

The subsystem an object belongs to, from its path inside the build tree.

Definition at line 39 of file symbol_coupling.py.

Referenced by collect().

nm()

symbol_coupling.nm	(		obj,
			args
	)

Definition at line 51 of file symbol_coupling.py.

Referenced by collect().

Variable Documentation

LAYER

dict symbol_coupling.LAYER

Initial value:

=  {'external': 0, 'win': 0, 'system': 0, 'common': 1, 'math': 1, 'colorprofiles': 1, 'pixel': 2, 'control': 3,
         'gui': 4, 'widgets': 4,   # widgets/ = reusable GTK widgets, no app state 'develop': 5,
         'iop': 6, 'imageio': 6, 'libs': 7, 'views': 7, 'chart': 7,
         'apps': 10,   # executables link the orchestrator, so they sit ABOVE it 'app': 9}

Definition at line 31 of file symbol_coupling.py.

OBJ_RE

symbol_coupling.OBJ_RE = re.compile(r'\.dir/(.*)\.(?:c|cc|cpp)\.o$')

Definition at line 36 of file symbol_coupling.py.