| |
| Our long term goal is to move to structure Valgrind's top level as a |
| set of well-defined modules. Much of the difficulty in maintaining |
| the beast is caused by the lack of clear boundaries, definitions and |
| semantics for subsystems (modules), and in particular a lack of |
| clarity about which modules may depend on which others. The ongoing |
| modularisation activities are aimed at dealing with this problem. |
| |
| Architecture dependent stuff will be chopped up and placed into the |
| relevant modules. Since the system's top level is now to be |
| structured as modules with clearly delimited areas of functionality, |
| directories such as 'amd64', 'amd64-linux', etc, cannot continue to |
| exist long-term. These trees contain mish-mashes of functionality |
| from multiple different modules, and so make no sense as top-level |
| entities in a scheme where all top-level entities are modules. |
| |
| This process is ongoing. Consequently some of the code in coregrind/ |
| has been bought into the module structure, but much hasn't. A naming |
| scheme distinguishes the done vs not-done stuff: |
| |
| Consider a module of name 'foo'. |
| |
| If 'foo' is implemented in a single C file, and requires no other |
| files, it will live in coregrind/m_foo.c. |
| |
| Otherwise (if 'foo' requires more than one C file, or more than |
| zero private header files, or any other kind of auxiliary stuff) |
| then it will live in the directory coregrind/m_foo. |
| |
| Each module 'foo' must have two associated header files which describe |
| its public (exported) interface: |
| |
| include/pub_tool_foo.h |
| coregrind/pub_core_foo.h |
| |
| pub_tool_foo.h describes that part of the module's functionality that |
| is visible to tools. Hopefully this can be minimal or zero. If there |
| is nothing to visible to tool, pub_tool_foo.h can be omitted. |
| |
| pub_core_foo.h describes functionality that is visible to other |
| modules in the core. This is a strict superset of the visible-to-tool |
| functionality. Consequently, pub_core_foo.h *must* #include |
| pub_tool_foo.h, if it exists. pub_tool_foo.h *must not* #include |
| pub_core_foo.h, nor any other pub_core_ header for that matter. |
| |
| Module-private headers are named "priv_foo.h". |
| |
| No module may include the private headers of any other module. If a |
| type/enum/function/struct/whatever is stated in neither |
| include/pub_tool_foo.h nor coregrind/pub_core_foo.h then module 'foo' |
| DOES NOT EXPORT IT. |
| |
| Over time it is hoped to develop some simple Perl scripts to scan |
| source files for #includes so as to mechanically enforce these rules. |
| One of the most infuriating aspects of C is the total lack of support |
| for building properly abstracted subsystems. This is in sharp |
| comparison to languages such as Modula3, Haskell, ML, all of which |
| have support for modules built into the language, and hence such |
| boundaries are enforceable by the compiler. |
