|
From: <sv...@va...> - 2005-04-24 12:19:22
|
Author: sewardj Date: 2005-04-24 13:19:13 +0100 (Sun, 24 Apr 2005) New Revision: 3554 Added: trunk/coregrind/README_MODULES.txt Modified: trunk/coregrind/Makefile.am Log: Add statement-of-intent re top level module structure. Modified: trunk/coregrind/Makefile.am =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/coregrind/Makefile.am 2005-04-24 11:22:44 UTC (rev 3553) +++ trunk/coregrind/Makefile.am 2005-04-24 12:19:13 UTC (rev 3554) @@ -37,7 +37,7 @@ =20 EXTRA_DIST =3D \ valgrind.vs \ - gen_toolint.pl toolfuncs.def + gen_toolint.pl toolfuncs.def README_MODULES.txt =20 BUILT_SOURCES =3D vg_toolint.c vg_toolint.h CLEANFILES =3D vg_toolint.c vg_toolint.h Added: trunk/coregrind/README_MODULES.txt =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/coregrind/README_MODULES.txt 2005-04-24 11:22:44 UTC (rev 3553) +++ trunk/coregrind/README_MODULES.txt 2005-04-24 12:19:13 UTC (rev 3554) @@ -0,0 +1,58 @@ + +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'. =20 + + 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. The file +must still exist even if it defines nothing. + +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 may #include pub_tool_foo.h, but not the +other way round. + +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. |