aboutsummaryrefslogtreecommitdiff
path: root/pretty-printers/README
diff options
context:
space:
mode:
authorSiddhesh Poyarekar <siddhesh@sourceware.org>2016-07-11 20:32:12 +0530
committerSiddhesh Poyarekar <siddhesh@sourceware.org>2016-07-11 20:32:12 +0530
commitc10f90dcef42092a96007fed7e77f9d470e5bb76 (patch)
treed4e260bbfec4a61d50a17f3be8fc64a0b7b01b4b /pretty-printers/README
parent26c2910ac6889dd21f128d9071418492d544a2dc (diff)
downloadglibc-c10f90dcef42092a96007fed7e77f9d470e5bb76.tar
glibc-c10f90dcef42092a96007fed7e77f9d470e5bb76.tar.gz
glibc-c10f90dcef42092a96007fed7e77f9d470e5bb76.tar.bz2
glibc-c10f90dcef42092a96007fed7e77f9d470e5bb76.zip
Revert "Add pretty printers for the NPTL lock types"
This reverts commit 62ce266b0b261def2c6329be9814ffdcc11964d6. The change is not mature enough because it needs the following fixes: 1. Redirect test output to a file like other tests 2. Eliminate the need to use a .gdbinit because distributions will break without it. I should have caught that but I was in too much of a hurry to get the patch in :/ 3. Feature checking during configure to determine things like minimum required gdb version, python-pexpect version, etc. to make sure that tests work correctly.
Diffstat (limited to 'pretty-printers/README')
-rw-r--r--pretty-printers/README130
1 files changed, 0 insertions, 130 deletions
diff --git a/pretty-printers/README b/pretty-printers/README
deleted file mode 100644
index ff35d7e6db..0000000000
--- a/pretty-printers/README
+++ /dev/null
@@ -1,130 +0,0 @@
-README for the glibc Python pretty printers
--------------------------------------------
-
-Pretty printers are gdb extensions that allow it to print useful, human-readable
-information about a program's variables. For example, for a pthread_mutex_t
-gdb would usually output something like this:
-
-(gdb) print mutex
-$1 = {
- __data = {
- __lock = 22020096,
- __count = 0,
- __owner = 0,
- __nusers = 0,
- __kind = 576,
- __spins = 0,
- __elision = 0,
- __list = {
- __prev = 0x0,
- __next = 0x0
- }
- },
- __size = "\000\000P\001", '\000' <repeats 12 times>, "@\002", '\000' <repeats 21 times>,
- __align = 22020096
-}
-
-However, with a pretty printer gdb will output something like this:
-
-(gdb) print mutex
-$1 = pthread_mutex_t = {
- Type = Normal,
- Status = Unlocked,
- Robust = No,
- Shared = No,
- Protocol = Priority protect,
- Priority ceiling = 42
-}
-
-Before printing a value, gdb will first check if there's a pretty printer
-registered for it. If there is, it'll use it, otherwise it'll print the value
-as usual. Pretty printers can be registered in various ways; for our purposes
-we register them for the current objfile by calling
-gdb.printing.register_pretty_printer().
-
-Currently our printers are based on gdb.RegexpCollectionPrettyPrinter, which
-means they'll be triggered if the type of the variable we're printing matches
-a given regular expression. For example, MutexPrinter will be triggered if
-our variable's type matches the regexp '^pthread_mutex_t$'.
-
-Besides the printers themselves, each module may have a constants file which the
-printers will import. These constants are generated from C headers during the
-build process, and need to be in the Python search path when loading the
-printers.
-
-
-Installing and loading
-----------------------
-
-The pretty printers and their constant files may be installed in different paths
-for each distro, though gdb should be able to automatically load them by itself.
-When in doubt, you can use the 'info pretty printer' gdb command to list the
-loaded pretty printers.
-
-If the printers aren't automatically loaded for some reason, you should add the
-following to your .gdbinit:
-
-python
-import sys
-sys.path.insert(0, '/path/to/constants/file/directory')
-end
-
-source /path/to/printers.py
-
-If you're building glibc manually, '/path/to/constants/file/directory' should be
-'/path/to/glibc-build/submodule', where 'submodule' is e.g. nptl.
-
-
-Testing
--------
-
-The pretty printers come with a small test suite based on PExpect, which is a
-Python module with Expect-like features for spawning and controlling interactive
-programs. Each printer has a corresponding C program and a Python script
-that uses PExpect to drive gdb through the program and compare its output to
-the expected printer's.
-
-The tests run on the glibc host, which is assumed to have both gdb and PExpect;
-if any of those is absent the tests will fail with code 77 (UNSUPPORTED).
-Native builds can be tested simply by doing 'make check'; cross builds must use
-cross-test-ssh.sh as test-wrapper, like this:
-
-make test-wrapper='/path/to/scripts/cross-test-ssh.sh user@host' check
-
-(Remember to share the build system's filesystem with the glibc host's through
-NFS or something similar).
-
-Running 'make check' on a cross build will only compile the test programs,
-without running the scripts.
-
-
-Known issues
-------------
-
-* Pretty printers are inherently coupled to the code they're targetting, thus
-any changes to the target code must also update the corresponding printers.
-On the plus side, the printer code itself may serve as a kind of documentation
-for the target code.
-
-* Older versions of the gdb Python API have a bug where
-gdb.RegexpCollectionPrettyPrinter would not be able to get a value's real type
-if it was typedef'd. This would cause gdb to ignore the pretty printers for
-types like pthread_mutex_t, which is defined as:
-
-typedef union
-{
- ...
-} pthread_mutex_t;
-
-This was fixed in commit 1b588015839caafc608a6944a78aea170f5fb2f6. However,
-typedef'ing an already typedef'd type may cause a similar issue, e.g.:
-
-typedef pthread_mutex_t mutex;
-mutex a_mutex;
-
-Here, trying to print a_mutex won't trigger the pthread_mutex_t printer.
-
-* The test programs must be compiled without optimizations. This is necessary
-because the test scripts rely on the C code structure being preserved when
-stepping through the programs. Things like aggressive instruction reordering
-or optimizing variables out may make this kind of testing impossible.