1
2Our long term goal is to move to structure Valgrind's top level as a
3set of well-defined modules.  Much of the difficulty in maintaining
4the beast is caused by the lack of clear boundaries, definitions and
5semantics for subsystems (modules), and in particular a lack of
6clarity about which modules may depend on which others.  The ongoing
7modularisation activities are aimed at dealing with this problem.
8
9Architecture dependent stuff will be chopped up and placed into the
10relevant modules.  Since the system's top level is now to be
11structured as modules with clearly delimited areas of functionality,
12directories such as 'amd64', 'amd64-linux', etc, cannot continue to
13exist long-term.  These trees contain mish-mashes of functionality
14from multiple different modules, and so make no sense as top-level
15entities in a scheme where all top-level entities are modules.
16
17This process is ongoing.  Consequently some of the code in coregrind/
18has been bought into the module structure, but much hasn't.  A naming
19scheme distinguishes the done vs not-done stuff:
20
21  Consider a module of name 'foo'.
22
23  If 'foo' is implemented in a single C file, and requires no other
24  files, it will live in coregrind/m_foo.c.
25
26  Otherwise (if 'foo' requires more than one C file, or more than
27  zero private header files, or any other kind of auxiliary stuff)
28  then it will live in the directory coregrind/m_foo.
29
30Each module 'foo' must have two associated header files which describe
31its public (exported) interface:
32
33  include/pub_tool_foo.h
34  coregrind/pub_core_foo.h
35
36pub_tool_foo.h describes that part of the module's functionality that
37is visible to tools.  Hopefully this can be minimal or zero.  If there
38is nothing to visible to tool, pub_tool_foo.h can be omitted.
39
40pub_core_foo.h describes functionality that is visible to other
41modules in the core.  This is a strict superset of the visible-to-tool
42functionality.  Consequently, pub_core_foo.h *must* #include
43pub_tool_foo.h, if it exists.  pub_tool_foo.h *must not* #include
44pub_core_foo.h, nor any other pub_core_ header for that matter.
45
46Module-private headers are named "priv_foo.h".
47
48No module may include the private headers of any other module.  If a
49type/enum/function/struct/whatever is stated in neither
50include/pub_tool_foo.h nor coregrind/pub_core_foo.h then module 'foo'
51DOES NOT EXPORT IT.
52
53Over time it is hoped to develop some simple Perl scripts to scan
54source files for #includes so as to mechanically enforce these rules.
55One of the most infuriating aspects of C is the total lack of support
56for building properly abstracted subsystems.  This is in sharp
57comparison to languages such as Modula3, Haskell, ML, all of which
58have support for modules built into the language, and hence such
59boundaries are enforceable by the compiler.
60