
DeadStrip Utility Documentation

Version 1.21 mod

This is a non-official modification, by Joe Forster/STA, of the original DeadStrip, by Dorian Weber.
http://sta.c64.org/winprg.html#deadstrip

Frequently Asked Questions

Q: What's all this about?
A: DeadStrip is a tool designed to perform dependency analysis and dead function/data removal on MinGW/gcc generated object files.

Q: But doesn't the compiler do this already?
A: No. The compiler doesn't know enough about the global contexts an object file might be linked into to do a reasonable strip of unreferenced code and data. It does however perform local optimization, i.e. in each object file.

Q: Okay, what about the linker?
A: Yes, the linker would be able to do dependency analysis, because it's got a global view onto the data. There's even a command line switch that enables this sort of global optimization; unfortunately it doesn't work under Windows.

Q: What is 'dead code stripping' anyway?
A: Removing code from your executable file that can be proven not to be in use. This reduces the total size of your apps.

Q: Couldn't I just remove all the unused functions by commenting them out?
A: You could, of course. But you're likely to forget some dependencies on larger projects, resulting in loads of linker errors and many hours of fun. Just imagine a larger framework you'd like to include in your project. You use just one function, because you're too lazy to reinvent the wheel. The compiler won't complain and the linker will link a nice XXL executable, not only including the PNG-loader but also a whole database management system, to manage your images in C++. This is the gap DeadStrip aims to fill.

Q: Then DeadStrip is an alternative linker?
A: No. You still use whatever linker you like to use. DeadStrip only hooks into the compiler-linker toolchain and analyses the object files before the linker sees them, removing all unused sections. When it's done, it calls the linker.

Q: Aren't there any other tools, that do the same already?
A: I've searched about one month for some tool like this, reading nearly every newsgroup entry containing the word GCC (there's a lot of them, trust me) and all I found, was some alternative linker contained in a large compiler-IDE framework that said it could do what I wanted. The final executable was larger than before when I was still linking using ld. Additionally ld has much more options when it comes down to fine tuning. So I decided to write that tool myself and still be able to use my favourite linker.

Q: I'm missing feature XY.
A: Then you've got a couple of options. If this feature is of major importance to you and you're not able to write it for yourself, ask me. If I like the idea, I might be implementing it and provide an update.
   But more reliable than me, is you. If you're able to write it for yourself, either by attaching another tool to the output of DeadStrip, or by contributing to the tools code, feel free to do so. DeadStrip provides XML-like output of various computed information and comes with full platform independent C source code. I would be happy to hear from you in those cases. Although I strictly encourage you to contribute to the source, please don't provide links on your site to your modified version saying that this is the "official" one (that is, my one). You can, however, modify your own version and present it as a modification from you. Credits aren't necessary.

Q: I found a bug.
A: Mail me with a detailed description of the error and provide some source code, if necessary, or try to fix it yourself and mail me afterwards :). My e-mail address is weber t informatik.hu-berlin.de.

Syntax

deadstrip [Options] file...
  Options:
    --help                display this help
    --dcmd                dumps the command line
    --ddis                dumps discarted sections
    --duse                dumps used sections
    --dmap                dump the dependency map
    --linker <filename>   use alternative linker (default: ld)
    --dnrm                do not remove any sections
    --rems <section>      REMoVe a Section
    --save <item>         save an item and its dependencies
      > just pass the decorated variable/function name, not the section
      > the main function gets saved by default

Additional Notes

- all dumps are printed to stdout - use the pipe symbol to redirect them, if necessary
- all switches that DeadStrip doesn't recognize are passed to the linker
- you should use the -ffunction-sections and/or -fdata-sections options, in order to generate appropriate section-partitioning; if you don't, DeadStrip won't be able to strip anything
- excessive section partitioning will increase the size of your exe, but compression tools like UPX can merge all sections afterwards
- when saving sections, be sure to only provide the decorated function/data name, not the prefix that the compiler generates
  - plain C functions are not decorated at all, so when you need to save a function called "mainCRTStartup", pass this name to DeadStrip
  - C++ functions are decorated according to their parameters, namespace and member information; you may need to look up their names using objdump from the binutils
  - you can optionally place the functions that you want to be save into a section of your choice by using gcc's __attribute__((section("myName"))). DeadStrip doesn't strip code located in unknown sections.
- DeadStrip depends on some tools, that are provided by binutils
  - namely objdump and objcopy
  - that means, you should have DeadStrip located, where those two tools reside (e.g. MinGW/bin/)

Installation

Just drop the deadstrip.exe executable into the directory of your binutils, then configure your IDE or makefile to call DeadStrip instead of the linker, but provide the original linker using the --linker switch. Finally enable compiler options -ffunction-sections and/or -fdata-sections for release builds.
Section partitioning will not remove all redundant constants. The dsasmpp.exe executable is an assembler preprocessor that moves each constant (labels in the .rdata section) into its own section so that they can be kept or removed independently.
You may rename deadstrip.exe to ld.exe and/or dsasmpp.exe to as.exe so that they are used in place of the original linker/assembler. In this case, first rename the real ld.exe to ld-real.exe and/or as.exe to as-real.exe.
When using 32-bit binutils with 64-bit target, rename the executables to x86_64-pc-mingw32-*.exe and they will automatically use binutils with the same name prefix. This can also be forced with the --x64 option.

Version History

Version 1.21 mod (Joe Forster/STA)
- Prefixes the names of temporary object files with the name of the linker output (default: a.exe), for parallel compilation (make -j).

Version 1.2 mod (Joe Forster/STA)
- New assembler preprocessor to move each constant into its own section.
- Discards completely redundant object files.
- Deletes the temporary, stripped copies of object files afterwards.
- Automatically uses 32-bit binutils with 64-bit target (x86_64-pc-mingw32-*.exe). This can also be forced with the --x64 option.
- Can be used in place of linker/assembler (no need to change makefile or IDE settings), automatically calls *-real.exe.
- Added WinMain and DllMain as other possible entry points.
- New --rems option to explicitly remove sections.

Version 1.1 (Dorian Weber)
- Fixed a severe bug concerning the stripping of virtual functions. DeadStrip should be completely compatible with C++ now.
- Noticed that references from the relocation section could safely be ignored during analysis. Code referenced only from there gets stripped now.

Version 1.0
This is the first release version, everything seems to work.
