unusedcode.README

   1 unusedcode.easy is generated via callcatcher[1] and filtered to remove some
   2 tricky edge-cases (see Makefile), e.g. anything which could plausibly be
   3 dlsymed or any symbol defined in an external library bundled into LibreOffice
   4 which doesn't happen to get used by LibreOffice.
   5
   6 unusedcode.easy is generated on an x86_64 --enable-debug --enable-dbgutil
   7 configuration.
   8
   9 Code listed as unused is code that gcc outputs but that nothing calls
  10 (or takes the address of).
  11
  12 a) It's possible that some other platform or configuration uses the code,
  13    so manual inspection is always required.
  14 b) At the time of writing the majority of unused code now originates via
  15    macros, mostly from pre-STL containers, see [2] for killing two birds
  16    with one stone. These are typically methods of signatures...
  17         *::Insert
  18         *::Remove
  19         *::DeleteAndDestroy
  20         *::Replace
  21 c) callcatcher ignores virtuals. But implementations of "pure virtuals"
  22    are not actually virtual methods. If something is declared pure virtual
  23    and provides an impl and that base-class impl is not explicitly called
  24    anywhere, then that impl can go away.
  25 d) gcc will only emit code for inlines if those inlines are used, so
  26    sometimes something is listed correctly as unused but some inline
  27    code takes a pointer or reference to something which cannot be
  28    instantiated so removal of some method/class fails at build time because
  29    gcc never emits any code for the the unused inline but trips over it at
  30    compile time after an attempt at removal. i.e. generally the inline method
  31    can go as well because nothing calls it either, a double win.
  32 e) if a constructor is listed as unused, and it's the *only* ctor in the class,
  33    then no object of that class can be constructed, so the whole thing is
  34    unused, which can lead to a whole cascade of tricky but logical fallout.
  35 f) if a destructor is listed as unused, and a constructor isn't, then there's
  36    a leak somewhere, and the destructor most likely *should* be called.
  37 g) there's more actually unused code then what's listed. The idea is that what's
  38    listed is definitely unused under the generation configuration, not that
  39    it's a list of all unused code. If the count of unused easy hits 0 then
  40    we can have a look at the non-easy and if that hits 0, then strip out
  41    code from the "release" binaries which only makes sense in debug/dbgutil
  42    configurations, and then tackle unused virtual method slots :-)
  43
  44 Symbols that are known to be false alarms are listed in: unused.exclude
  45
  46 [1] http://www.skynet.ie/~caolan/Packages/callcatcher.html
  47 [2] https://bugs.freedesktop.org/show_bug.cgi?id=38832