third_party/tcmalloc/vendor/README_windows.txt

   1 --- COMPILING
   2
   3 This project has begun being ported to Windows.  A working solution
   4 file exists in this directory:
   5     gperftools.sln
   6
   7 You can load this solution file into VC++ 7.1 (Visual Studio 2003) or
   8 later -- in the latter case, it will automatically convert the files
   9 to the latest format for you.
  10
  11 When you build the solution, it will create a number of unittests,
  12 which you can run by hand (or, more easily, under the Visual Studio
  13 debugger) to make sure everything is working properly on your system.
  14 The binaries will end up in a directory called "debug" or "release" in
  15 the top-level directory (next to the .sln file).  It will also create
  16 two binaries, nm-pdb and addr2line-pdb, which you should install in
  17 the same directory you install the 'pprof' perl script.
  18
  19 I don't know very much about how to install DLLs on Windows, so you'll
  20 have to figure out that part for yourself.  If you choose to just
  21 re-use the existing .sln, make sure you set the IncludeDir's
  22 appropriately!  Look at the properties for libtcmalloc_minimal.dll.
  23
  24 Note that these systems are set to build in Debug mode by default.
  25 You may want to change them to Release mode.
  26
  27 To use tcmalloc_minimal in your own projects, you should only need to
  28 build the dll and install it someplace, so you can link it into
  29 further binaries.  To use the dll, you need to add the following to
  30 the linker line of your executable:
  31    "libtcmalloc_minimal.lib" /INCLUDE:"__tcmalloc"
  32
  33 Here is how to accomplish this in Visual Studio 2005 (VC8):
  34
  35 1) Have your executable depend on the tcmalloc library by selecting
  36    "Project Dependencies..." from the "Project" menu.  Your executable
  37    should depend on "libtcmalloc_minimal".
  38
  39 2) Have your executable depend on a tcmalloc symbol -- this is
  40    necessary so the linker doesn't "optimize out" the libtcmalloc
  41    dependency -- by right-clicking on your executable's project (in
  42    the solution explorer), selecting Properties from the pull-down
  43    menu, then selecting "Configuration Properties" -> "Linker" ->
  44    "Input".  Then, in the "Force Symbol References" field, enter the
  45    text "__tcmalloc" (without the quotes).  Be sure to do this for both
  46    debug and release modes!
  47
  48 You can also link tcmalloc code in statically -- see the example
  49 project tcmalloc_minimal_unittest-static, which does this.  For this
  50 to work, you'll need to add "/D PERFTOOLS_DLL_DECL=" to the compile
  51 line of every perftools .cc file.  You do not need to depend on the
  52 tcmalloc symbol in this case (that is, you don't need to do either
  53 step 1 or step 2 from above).
  54
  55 An alternative to all the above is to statically link your application
  56 with libc, and then replace its malloc with tcmalloc.  This allows you
  57 to just build and link your program normally; the tcmalloc support
  58 comes in a post-processing step.  This is more reliable than the above
  59 technique (which depends on run-time patching, which is inherently
  60 fragile), though more work to set up.  For details, see
  61    https://groups.google.com/group/google-perftools/browse_thread/thread/41cd3710af85e57b
  62
  63
  64 --- THE HEAP-PROFILER
  65
  66 The heap-profiler has had a preliminary port to Windows.  It has not
  67 been well tested, and probably does not work at all when Frame Pointer
  68 Optimization (FPO) is enabled -- that is, in release mode.  The other
  69 features of perftools, such as the cpu-profiler and leak-checker, have
  70 not yet been ported to Windows at all.
  71
  72
  73 --- WIN64
  74
  75 The function-patcher has to disassemble code, and is very
  76 x86-specific.  However, the rest of perftools should work fine for
  77 both x86 and x64.  In particular, if you use the 'statically link with
  78 libc, and replace its malloc with tcmalloc' approach, mentioned above,
  79 it should be possible to use tcmalloc with 64-bit windows.
  80
  81 As of perftools 1.10, there is some support for disassembling x86_64
  82 instructions, for work with win64.  This work is preliminary, but the
  83 test file preamble_patcher_test.cc is provided to play around with
  84 that a bit.  preamble_patcher_test will not compile on win32.
  85
  86
  87 --- ISSUES
  88
  89 NOTE FOR WIN2K USERS: According to reports
  90 (http://code.google.com/p/gperftools/issues/detail?id=127)
  91 the stack-tracing necessary for the heap-profiler does not work on
  92 Win2K.  The best workaround is, if you are building on a Win2k system
  93 is to add "/D NO_TCMALLOC_SAMPLES=" to your build, to turn off the
  94 stack-tracing.  You will not be able to use the heap-profiler if you
  95 do this.
  96
  97 NOTE ON _MSIZE and _RECALLOC: The tcmalloc version of _msize returns
  98 the size of the region tcmalloc allocated for you -- which is at least
  99 as many bytes you asked for, but may be more.  (btw, these *are* bytes
 100 you own, even if you didn't ask for all of them, so it's correct code
 101 to access all of them if you want.)  Unfortunately, the Windows CRT
 102 _recalloc() routine assumes that _msize returns exactly as many bytes
 103 as were requested.  As a result, _recalloc() may not zero out new
 104 bytes correctly.  IT'S SAFEST NOT TO USE _RECALLOC WITH TCMALLOC.
 105 _recalloc() is a tricky routine to use in any case (it's not safe to
 106 use with realloc, for instance).
 107
 108
 109 I have little experience with Windows programming, so there may be
 110 better ways to set this up than I've done!  If you run across any
 111 problems, please post to the google-perftools Google Group, or report
 112 them on the gperftools Google Code site:
 113    http://groups.google.com/group/google-perftools
 114    http://code.google.com/p/gperftools/issues/list
 115
 116 -- craig
 117
 118 Last modified: 2 February 2012