sewardj | cc9549a | 2005-04-24 12:19:13 +0000 | [diff] [blame] | 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 |
sewardj | 5efa55f | 2005-04-24 14:34:42 +0000 | [diff] [blame] | 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. |
sewardj | cc9549a | 2005-04-24 12:19:13 +0000 | [diff] [blame] | 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 |
sewardj | 5efa55f | 2005-04-24 14:34:42 +0000 | [diff] [blame] | 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. |
sewardj | cc9549a | 2005-04-24 12:19:13 +0000 | [diff] [blame] | 45 | |
njn | 717cde5 | 2005-05-10 02:47:21 +0000 | [diff] [blame] | 46 | Module-private headers are named "priv_foo.h". |
| 47 | |
sewardj | cc9549a | 2005-04-24 12:19:13 +0000 | [diff] [blame] | 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. |