docs/internals/directory-structure.txt

   1 -------------------------------------------------------------------
   2 Guide to the directory structure
   3 -------------------------------------------------------------------
   4 [This should be merged with coregrind/README_MODULES.txt]
   5
   6 Valgrind has 2 main levels of genericity.
   7
   8  1. Multiple tools, plus the core.
   9  2. Multiple architectures, OSes, and platforms (arch/OS combinations).
  10
  11 This file is a guide to where different things live.
  12
  13
  14 Basic layout
  15 ------------
  16 1. Core stuff lives in:
  17     - include/              for declarations that must be seen by tools
  18     - coregrind/            for code that need not be seen by tools
  19
  20    Some subdirs of coregrind/ hold modules that consist of multiple files.
  21
  22    Tool stuff lives in:
  23     - $TOOL/                main files
  24     - $TOOL/tests           regression tests
  25     - $TOOL/docs            documentation
  26
  27    Other stuff lives in:
  28     - docs/                 main, non-tool-specific docs
  29     - tests/                regression test machinery
  30     - nightly/              overnight test stuff (should be in tests/)
  31     - auxprogs/             auxiliary programs
  32
  33 2. Generic things go in the directory specified in (1).
  34
  35    Arch-specific, OS-specific, or platform-specific things are sprinkled
  36    throughout the code -- there is no single place for all the
  37    architecture-specific things, for example.
  38
  39    Sometimes we have a whole file holding things specific to a particular
  40    arch/OS/platform.  Such files have an appropriate suffix, eg.
  41    sigframe-x86-linux.c.
  42
  43    More often we use #ifdefs inside source files to specify the different
  44    cases for different archs/OSes/platforms.  It's pretty straightforward.
  45
  46    A final case:  arch-specific regression tests for tools go in a
  47    subdirectory, eg. cachegrind/tests/x86/.
  48
  49
  50 Guide to headers
  51 ----------------
  52 See coregrind/README_MODULES.txt for details of the core/tool header file
  53 split.
  54
  55 Note that every single C file will #include pub_basics.h.  Every single asm
  56 file will #include pub_basics_asm.h.
  57
  58 Our versions of kernel types are in the vki*.h headers.
  59
  60 When searching for something, rgrep is very useful.  If you don't have a
  61 version of rgrep, use a command something like this:
  62
  63    find . -name '*.h' | xargs grep <pattern>
  64
  65    find . -name '*.h' \
  66           -type f \
  67           -not -path '*.svn\/*' | xargs grep "$1"
  68
  69 The -name option gives the file wildcard, the -type says "look in normal
  70 files only" and the -not -path tells it to not look in Subversions hidden
  71 directories.
  72