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