README_PACKAGERS

   1
   2 Greetings, packaging person!  This information is aimed at people
   3 building binary distributions of Valgrind.
   4
   5 Thanks for taking the time and effort to make a binary distribution of
   6 Valgrind.  The following notes may save you some trouble.
   7
   8 -- If your toolchain (compiler, linker) support lto, using the configure
   9    option --enable-lto=yes will produce a smaller/faster valgrind
  10    (up to 10%).
  11
  12 -- Do not ship your Linux distro with a completely stripped
  13    /lib/ld.so.  At least leave the debugging symbol names on -- line
  14    number info isn't necessary.  If you don't want to leave symbols on
  15    ld.so, alternatively you can have your distro install ld.so's
  16    debuginfo package by default, or make ld.so.debuginfo be a
  17    requirement of your Valgrind RPM/DEB/whatever.
  18
  19    Reason for this is that Valgrind's Memcheck tool needs to intercept
  20    calls to, and provide replacements for, some symbols in ld.so at
  21    startup (most importantly strlen).  If it cannot do that, Memcheck
  22    shows a large number of false positives due to the highly optimised
  23    strlen (etc) routines in ld.so.  This has caused some trouble in
  24    the past.  As of version 3.3.0, on some targets (ppc32-linux,
  25    ppc64-linux), Memcheck will simply stop at startup (and print an
  26    error message) if such symbols are not present, because it is
  27    infeasible to continue.
  28
  29    It's not like this is going to cost you much space.  We only need
  30    the symbols for ld.so (a few K at most).  Not the debug info and
  31    not any debuginfo or extra symbols for any other libraries.
  32
  33
  34 -- (Unfortunate but true) When you configure to build with the
  35    --prefix=/foo/bar/xyzzy option, the prefix /foo/bar/xyzzy gets
  36    baked into valgrind.  The consequence is that you _must_ install
  37    valgrind at the location specified in the prefix.  If you don't,
  38    it may appear to work, but will break doing some obscure things,
  39    particularly doing fork() and exec().
  40
  41    So you can't build a relocatable RPM / whatever from Valgrind.
  42
  43
  44 -- Don't strip the debug info off lib/valgrind/$platform/vgpreload*.so
  45    in the installation tree.  Either Valgrind won't work at all, or it
  46    will still work if you do, but will generate less helpful error
  47    messages.  Here's an example:
  48
  49    Mismatched free() / delete / delete []
  50       at 0x40043249: free (vg_clientfuncs.c:171)
  51       by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
  52       by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
  53       by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
  54       Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
  55       at 0x4004318C: __builtin_vec_new (vg_clientfuncs.c:152)
  56       by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
  57       by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
  58       by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
  59
  60    This tells you that some memory allocated with new[] was freed with
  61    free().
  62
  63    Mismatched free() / delete / delete []
  64       at 0x40043249: (inside vgpreload_memcheck.so)
  65       by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
  66       by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
  67       by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
  68       Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
  69       at 0x4004318C: (inside vgpreload_memcheck.so)
  70       by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
  71       by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
  72       by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
  73
  74    This isn't so helpful.  Although you can tell there is a mismatch,
  75    the names of the allocating and deallocating functions are no longer
  76    visible.  The same kind of thing occurs in various other messages
  77    from valgrind.
  78
  79
  80 -- Don't strip symbols from libexec/valgrind/* in the installation tree.
  81    Doing so will likely cause problems.  Removing the line number info is
  82    probably OK (at least for some of the files in that directory), although
  83    that has not been tested by the Valgrind developers.
  84
  85    One consequence of stripping these binaries is that if Valgrind crashes
  86    it won't be able to print out a useful callstack. Here is an example
  87    posted on Stack Overflow
  88
  89       valgrind: the 'impossible' happened: Killed by fatal signal
  90
  91       host stacktrace:
  92       ==7732== at 0x38091C12: ??? (in /usr/lib/valgrind/memcheck-amd64-linux)
  93       ==7732== by 0x38050E84: ??? (in /usr/lib/valgrind/memcheck-amd64-linux)
  94       ==7732== by 0x380510A9: ??? (in /usr/lib/valgrind/memcheck-amd64-linux)
  95       ==7732== by 0x380D4F7B: ??? (in /usr/lib/valgrind/memcheck-amd64-linux)
  96       ==7732== by 0x380E3946: ??? (in /usr/lib/valgrind/memcheck-amd64-linux)
  97
  98   Bug reports like this are less likely to be resolved.
  99
 100 -- Please test the final installation works by running it on something
 101    huge.  I suggest checking that it can start and exit successfully
 102    both Firefox and OpenOffice.org.  I use these as test programs, and I
 103    know they fairly thoroughly exercise Valgrind.  The command lines to use
 104    are:
 105
 106    valgrind -v --trace-children=yes firefox
 107
 108    valgrind -v --trace-children=yes soffice
 109
 110
 111 If you find any more hints/tips for packaging, please report
 112 it as a bugreport. See http://www.valgrind.org for details.