docs/directory-structure

-------------------------------------------------------------------
Guide to the directory structure
-------------------------------------------------------------------
Valgrind has 2 main levels of genericity.
 
 1. Multiple tools, plus the core.
 2. Multiple architectures, OSes, and platforms (arch/OS combinations).

This requires a moderately complex directory structure.  This file is a
guide to where different things live.


Basic layout
------------
1. Core stuff lives in:
    - include/              for declarations that must be seen by tools
    - coregrind/            for code that need not be seen by tools
    - coregrind/demangle/   the demangler

   Tool stuff lives in:
    - $TOOL/                main files
    - $TOOL/tests           regression tests
    - $TOOL/docs            documentation

   Other stuff lives in:
    - docs/                 main, non-tool-specific docs
    - tests/                regression test machinery
    - nightly/              overnight test stuff (should be in tests/)
    - auxprogs/             auxiliary programs

2. Generic things go in the directory specified in (1).  

   Arch-specific, OS-specific, or platform-specific things go within a
   subdirectory of the directory specified by step (1) above.

   For example: 
   - Cachegrind's main generic code goes in cachegrind/.
   - Cachegrind's x86-specific code goes in cachegrind/x86/.
   - Cachegrind's x86-specific tests go  in cachegrind/tests/x86/.
   - x86/Linux-specific declarations that must be visible to tools go in
     include/x86-linux/.

   
Guide to headers
----------------
Finding declarations in headers is not always easy.  The above rules dictate
which directory something should go in.  As well as that, there are some things
that must be visible in both C and assembly code files, but most things only be
visible in C files; things that must be both C-visible and asm-visible go in
files called *_asm.h.

The most important header files are (at the time of writing):
- include/tool.h     (auto-generated from tool.h.base + toolfuncs.def)
- include/tool_asm.h
- $ARCH/tool_arch.h
- $OS/vki.h
- $PLATFORM/vki*.h
- coregrind/{core.h,core_asm.h}
- $ARCH/{core_arch.h,core_arch_asm.h}
- $OS/core_os.h
- $PLATFORM/{core_platform.h,vki_unistd.h}

There are a few others, but that is most of them.

Having read the above text, it should be clear what is found in each of them.
For example, coregrind/core_asm.h contains all the generic
(non-arch/OS/platform-specific) declarations which should not be seen by
tools and must be visible to both C and asm code.

When searching for something, rgrep is very useful.  If you don't have a
version of rgrep, use a command something like this:

   find . -name '*.h' | xargs grep <pattern>

The comment at the top of coregrind/core.h has some additional information
about the exact hierarchy of the header files, but those details aren't
important for just finding and placing things.