docs/internals/module-structure.txt

   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.