]>
Commit | Line | Data |
---|---|---|
23b5cae1 MG |
1 | README for the glibc Python pretty printers |
2 | =========================================== | |
3 | ||
4 | Pretty printers are gdb extensions that allow it to print useful, human-readable | |
5 | information about a program's variables. For example, for a pthread_mutex_t | |
6 | gdb would usually output something like this: | |
7 | ||
8 | (gdb) print mutex | |
9 | $1 = { | |
10 | __data = { | |
11 | __lock = 22020096, | |
12 | __count = 0, | |
13 | __owner = 0, | |
14 | __nusers = 0, | |
15 | __kind = 576, | |
16 | __spins = 0, | |
17 | __elision = 0, | |
18 | __list = { | |
19 | __prev = 0x0, | |
20 | __next = 0x0 | |
21 | } | |
22 | }, | |
23 | __size = "\000\000P\001", '\000' <repeats 12 times>, "@\002", '\000' <repeats 21 times>, | |
24 | __align = 22020096 | |
25 | } | |
26 | ||
27 | However, with a pretty printer gdb will output something like this: | |
28 | ||
29 | (gdb) print mutex | |
30 | $1 = pthread_mutex_t = { | |
31 | Type = Normal, | |
6d523660 | 32 | Status = Not acquired, |
23b5cae1 MG |
33 | Robust = No, |
34 | Shared = No, | |
35 | Protocol = Priority protect, | |
36 | Priority ceiling = 42 | |
37 | } | |
38 | ||
39 | Before printing a value, gdb will first check if there's a pretty printer | |
40 | registered for it. If there is, it'll use it, otherwise it'll print the value | |
41 | as usual. Pretty printers can be registered in various ways; for our purposes | |
42 | we register them for the current objfile by calling | |
43 | gdb.printing.register_pretty_printer(). | |
44 | ||
45 | Currently our printers are based on gdb.RegexpCollectionPrettyPrinter, which | |
46 | means they'll be triggered if the type of the variable we're printing matches | |
47 | a given regular expression. For example, MutexPrinter will be triggered if | |
48 | our variable's type matches the regexp '^pthread_mutex_t$'. | |
49 | ||
50 | Besides the printers themselves, each module may have a constants file which the | |
51 | printers will import. These constants are generated from C headers during the | |
52 | build process, and need to be in the Python search path when loading the | |
53 | printers. | |
54 | ||
55 | ||
56 | Installing and loading | |
57 | ---------------------- | |
58 | ||
59 | The pretty printers and their constant files may be installed in different paths | |
60 | for each distro, though gdb should be able to automatically load them by itself. | |
61 | When in doubt, you can use the 'info pretty-printer' gdb command to list the | |
62 | loaded pretty printers. | |
63 | ||
64 | If the printers aren't automatically loaded for some reason, you should add the | |
65 | following to your .gdbinit: | |
66 | ||
67 | python | |
68 | import sys | |
69 | sys.path.insert(0, '/path/to/constants/file/directory') | |
70 | end | |
71 | ||
72 | source /path/to/printers.py | |
73 | ||
74 | If you're building glibc manually, '/path/to/constants/file/directory' should be | |
75 | '/path/to/glibc-build/submodule', where 'submodule' is e.g. nptl. | |
76 | ||
77 | ||
78 | Testing | |
79 | ------- | |
80 | ||
81 | The pretty printers come with a small test suite based on PExpect, which is a | |
82 | Python module with Expect-like features for spawning and controlling interactive | |
83 | programs. Each printer has a corresponding C program and a Python script | |
84 | that uses PExpect to drive gdb through the program and compare its output to | |
85 | the expected printer's. | |
86 | ||
87 | The tests run on the glibc host, which is assumed to have both gdb and PExpect; | |
88 | if any of those is absent the tests will fail with code 77 (UNSUPPORTED). | |
89 | Native builds can be tested simply by doing 'make check'; cross builds must use | |
90 | cross-test-ssh.sh as test-wrapper, like this: | |
91 | ||
92 | make test-wrapper='/path/to/scripts/cross-test-ssh.sh user@host' check | |
93 | ||
94 | (Remember to share the build system's filesystem with the glibc host's through | |
95 | NFS or something similar). | |
96 | ||
97 | Running 'make check' on a cross build will only compile the test programs, | |
98 | without running the scripts. | |
99 | ||
100 | ||
101 | Adding new pretty printers | |
102 | -------------------------- | |
103 | ||
104 | Adding new pretty printers to glibc requires following these steps: | |
105 | ||
106 | 1. Identify which constants must be generated from C headers, and write the | |
cb7be159 | 107 | corresponding .pysym file. See scripts/gen-as-const.py for more information |
23b5cae1 MG |
108 | on how this works. The name of the .pysym file must be added to the |
109 | 'gen-py-const-headers' variable in your submodule's Makefile (without the .pysym | |
110 | extension). | |
111 | ||
112 | 2. Write the pretty printer code itself. For this you can follow the gdb | |
113 | Python API documentation, and use the existing printers as examples. The printer | |
114 | code must import the generated constants file (which will have the same name | |
115 | as your .pysym file). The names of the pretty printer files must be added | |
116 | to the 'pretty-printers' variable in your submodule's Makefile (without the .py | |
117 | extension). | |
118 | ||
119 | 3. Write the unit tests for your pretty printers. The build system calls each | |
120 | test script passing it the paths to the test program source, the test program | |
121 | binary, and the printer files you added to 'pretty-printers' in the previous | |
122 | step. The test scripts, in turn, must import scripts/test_printers_common | |
123 | and call the init_test function passing it, among other things, the name of the | |
124 | set of pretty printers to enable (as seen by running 'info pretty-printer'). | |
125 | You can use the existing unit tests as examples. | |
126 | ||
127 | 4. Add the names of the pretty printer tests to the 'tests-printers' variable | |
128 | in your submodule's Makefile (without extensions). In addition, for each test | |
81e0662e CD |
129 | program you must define a corresponding CFLAGS-* and CPPFLAGS-* variable and |
130 | set it to $(CFLAGS-printers-tests) to ensure they're compiled correctly. For | |
131 | example, test-foo-printer.c requires the following: | |
23b5cae1 MG |
132 | |
133 | CFLAGS-test-foo-printer.c := $(CFLAGS-printers-tests) | |
81e0662e | 134 | CPPFLAGS-test-foo-printer.c := $(CFLAGS-printers-tests) |
23b5cae1 MG |
135 | |
136 | Finally, if your programs need to be linked with a specific library, you can add | |
137 | its name to the 'tests-printers-libs' variable in your submodule's Makefile. | |
138 | ||
139 | ||
140 | Known issues | |
141 | ------------ | |
142 | ||
143 | * Pretty printers are inherently coupled to the code they're targetting, thus | |
144 | any changes to the target code must also update the corresponding printers. | |
145 | On the plus side, the printer code itself may serve as a kind of documentation | |
146 | for the target code. | |
147 | ||
6d523660 TR |
148 | * There's no guarantee that the information the pretty printers provide is |
149 | complete, i.e. some details might be left off. For example, the pthread_mutex_t | |
150 | printers won't report whether a thread is spin-waiting in an attempt to acquire | |
151 | the mutex. | |
152 | ||
23b5cae1 MG |
153 | * Older versions of the gdb Python API have a bug where |
154 | gdb.RegexpCollectionPrettyPrinter would not be able to get a value's real type | |
155 | if it was typedef'd. This would cause gdb to ignore the pretty printers for | |
156 | types like pthread_mutex_t, which is defined as: | |
157 | ||
158 | typedef union | |
159 | { | |
160 | ... | |
161 | } pthread_mutex_t; | |
162 | ||
163 | This was fixed in commit 1b588015839caafc608a6944a78aea170f5fb2f6, and released | |
164 | as part of gdb 7.8. However, typedef'ing an already typedef'd type may cause | |
165 | a similar issue, e.g.: | |
166 | ||
167 | typedef pthread_mutex_t mutex; | |
168 | mutex a_mutex; | |
169 | ||
170 | Here, trying to print a_mutex won't trigger the pthread_mutex_t printer. | |
171 | ||
172 | * The test programs must be compiled without optimizations. This is necessary | |
173 | because the test scripts rely on the C code structure being preserved when | |
174 | stepping through the programs. Things like aggressive instruction reordering | |
175 | or optimizing variables out may make this kind of testing impossible. |