| njn | 009af89 | 2004-12-01 11:54:07 +0000 | [diff] [blame] | 1 | ------------------------------------------------------------------- |
| 2 | Guide to the directory structure |
| 3 | ------------------------------------------------------------------- |
| njn | 6d82819 | 2005-05-16 21:30:24 +0000 | [diff] [blame] | 4 | [16-May-2005: a lot of the stuff about arch/OS/platform specific code |
| 5 | is out of date in here. Hopefully, things have gotten simpler. --njn] |
| 6 | |
| njn | 009af89 | 2004-12-01 11:54:07 +0000 | [diff] [blame] | 7 | Valgrind has 2 main levels of genericity. |
| 8 | |
| 9 | 1. Multiple tools, plus the core. |
| 10 | 2. Multiple architectures, OSes, and platforms (arch/OS combinations). |
| 11 | |
| 12 | This requires a moderately complex directory structure. This file is a |
| 13 | guide to where different things live. |
| 14 | |
| 15 | |
| 16 | Basic layout |
| 17 | ------------ |
| 18 | 1. Core stuff lives in: |
| 19 | - include/ for declarations that must be seen by tools |
| 20 | - coregrind/ for code that need not be seen by tools |
| 21 | - coregrind/demangle/ the demangler |
| 22 | |
| 23 | Tool stuff lives in: |
| 24 | - $TOOL/ main files |
| 25 | - $TOOL/tests regression tests |
| 26 | - $TOOL/docs documentation |
| 27 | |
| 28 | Other stuff lives in: |
| 29 | - docs/ main, non-tool-specific docs |
| 30 | - tests/ regression test machinery |
| 31 | - nightly/ overnight test stuff (should be in tests/) |
| 32 | - auxprogs/ auxiliary programs |
| 33 | |
| 34 | 2. Generic things go in the directory specified in (1). |
| 35 | |
| 36 | Arch-specific, OS-specific, or platform-specific things go within a |
| 37 | subdirectory of the directory specified by step (1) above. |
| 38 | |
| 39 | For example: |
| 40 | - Cachegrind's main generic code goes in cachegrind/. |
| 41 | - Cachegrind's x86-specific code goes in cachegrind/x86/. |
| 42 | - Cachegrind's x86-specific tests go in cachegrind/tests/x86/. |
| 43 | - x86/Linux-specific declarations that must be visible to tools go in |
| 44 | include/x86-linux/. |
| 45 | |
| 46 | |
| 47 | Guide to headers |
| 48 | ---------------- |
| 49 | Finding declarations in headers is not always easy. The above rules dictate |
| 50 | which directory something should go in. As well as that, there are some things |
| 51 | that must be visible in both C and assembly code files, but most things only be |
| 52 | visible in C files; things that must be both C-visible and asm-visible go in |
| 53 | files called *_asm.h. |
| 54 | |
| 55 | The most important header files are (at the time of writing): |
| 56 | - include/tool.h (auto-generated from tool.h.base + toolfuncs.def) |
| 57 | - include/tool_asm.h |
| 58 | - $ARCH/tool_arch.h |
| 59 | - $OS/vki.h |
| 60 | - $PLATFORM/vki*.h |
| 61 | - coregrind/{core.h,core_asm.h} |
| 62 | - $ARCH/{core_arch.h,core_arch_asm.h} |
| 63 | - $OS/core_os.h |
| 64 | - $PLATFORM/{core_platform.h,vki_unistd.h} |
| 65 | |
| 66 | There are a few others, but that is most of them. |
| 67 | |
| 68 | Having read the above text, it should be clear what is found in each of them. |
| 69 | For example, coregrind/core_asm.h contains all the generic |
| 70 | (non-arch/OS/platform-specific) declarations which should not be seen by |
| 71 | tools and must be visible to both C and asm code. |
| 72 | |
| 73 | When searching for something, rgrep is very useful. If you don't have a |
| 74 | version of rgrep, use a command something like this: |
| 75 | |
| 76 | find . -name '*.h' | xargs grep <pattern> |
| 77 | |
| 78 | The comment at the top of coregrind/core.h has some additional information |
| 79 | about the exact hierarchy of the header files, but those details aren't |
| 80 | important for just finding and placing things. |
| 81 | |