callcatcher: update list, add README, remove some newly unused code

1 files changed, 39 insertions, 0 deletions

diff --git a/unusedcode.README b/unusedcode.README
new file mode 100644
index 000000000000..08f51b7bc85d
--- /dev/null
+++ b/unusedcode.README
@@ -0,0 +1,39 @@
+unusedcode.easy is generated via callcatcher[1] and filtered to remove some
+tricky edge-cases (see Makefile), e.g. anything which could plausibly be
+dlsymed or any symbol defined in an external library bundled into LibreOffice
+which doesn't happen to get used by LibreOffice.
+
+unusedcode.easy is generated on an x86_64 --enable-debug --enable-dbgutil
+configuration.
+
+Code listed as unused is code that gcc outputs but that nothing calls
+(or takes the address of).
+
+a) It's possible that some other platform or configuration uses the code,
+   so manual inspection is always required.
+b) At the time of writing the majority of unused code now originates via 
+   macros, mostly from pre-STL containers, see [2] for killing two birds
+   with one stone.
+c) callcatcher ignores virtuals. But implementations of "pure virtuals"
+   are not actually virtual methods. If something is declared pure virtual
+   and provides an impl and that base-class impl is not explicitly called
+   anywhere, then that impl can go away.
+d) gcc will only emit code for inlines if those inlines are used, so
+   sometimes something is listed correctly as unused but some inline
+   code takes a pointer or reference to something which cannot be 
+   instantiated so removal of some method/class fails at build time because
+   gcc never emits any code for the the unused inline but trips over it at
+   compile time after an attempt at removal. i.e. generally the inline method
+   can go as well because nothing calls it either, a double win.
+e) if a constructor is listed as unused, and it's the *only* ctor in the class,
+   then no object of that class can be construsted, so the whole thing is
+   unused, which can lead to a whole cascade of tricky but logical fallout.
+f) there's more actually unused code then what's listed. The idea is that what's
+   listed is definitely unused under the generation configuration, not that
+   it's a list of all unused code. If the count of unused easy hits 0 then
+   we can have a look at the non-easy and if that hits 0, then strip out
+   code from the "release" binaries which only makes sense in debug/dbgutil
+   configurations, and then tackle unused virtual method slots :-)
+
+[1] http://www.skynet.ie/~caolan/Packages/callcatcher.html
+[2] https://bugs.freedesktop.org/show_bug.cgi?id=38832