src/Debug-Hints.txt

   1 Debugging hints\r
   2 ===============\r
   3 \r
   4 This guide will show you how to debug TortoiseGit. In general there are\r
   5 three stages of debugging with increasing need of work:\r
   6 \r
   7 * Capturing debug strings\r
   8 * Using a debugger (to generate a stack trace)\r
   9 * Compile your own debug version\r
  10 \r
  11 Capture Debug Strings\r
  12 =====================\r
  13 \r
  14 TortoiseGit has some debug statements build in which are not generated\r
  15 and visible by default.\r
  16 \r
  17 You can enable the generation of those debug strings by setting\r
  18 "DebugOutputString" to "true" in TortoiseGit advanced settings.\r
  19 \r
  20 After restarting your computer (or TGitCache.exe, explorer.exe and/or\r
  21 TortoiseGitProc.exe) you can capture the debug strings using a tools like\r
  22 DebugView (http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx)\r
  23 from the SysInternals suite or WinDbg\r
  24 (http://msdn.microsoft.com/en-us/windows/hardware/gg463009.aspx).\r
  25 \r
  26 If you use DebugView and wish to report the values in Time column, you\r
  27 need to save the log file or log to file. Time column is not copied\r
  28 to clipboard.\r
  29 \r
  30 How to use a debugger\r
  31 =====================\r
  32 \r
  33 In order to generate a stack trace you can use a debugger like WinDbg\r
  34 (http://msdn.microsoft.com/en-us/windows/hardware/gg463009.aspx) or a\r
  35 Visual Studio IDE and attach it to a TortoiseGit process.\r
  36 \r
  37 To get a nice stack trace and resolve symbols, you can use our symbol server\r
  38 \r
  39     http://drdump.com:8080/public/TortoiseGit/7fbde3fc-94e9-408b-b5c8-62bd4e203570/symsrv/\r
  40 \r
  41 or download the debug symbols (https://download.tortoisegit.org/tgit/)\r
  42 which are only available for our releases.\r
  43 \r
  44 In WinDbg the symbol server can be used by issuing\r
  45 \r
  46     .sympath+ srv*c:\tmp*http://drdump.com:8080/public/TortoiseGit/7fbde3fc-94e9-408b-b5c8-62bd4e203570/symsrv/\r
  47 \r
  48 the URL for the Microsoft symbol server is:\r
  49 \r
  50     srv*c:\tmp*http://msdl.microsoft.com/download/symbols\r
  51 \r
  52 To debug the TortoiseProc part of TortoiseGit proceed as with any\r
  53 normal application.\r
  54 \r
  55 To debug the TGitCache exit the TGitCache.exe process and proceed\r
  56 as with any normal application. Exiting TGitCache.exe is necessary\r
  57 because only one instance of TGitCache may run at a time. To exit\r
  58 the TGitCache process set HKCU\Software\TortoiseGit\CacheTrayIcon\r
  59 to 1 and call "Exit" in the context menu of the tray icon.\r
  60 \r
  61 Compile your own debug version\r
  62 ==============================\r
  63 \r
  64 See build.txt and architecture.txt.\r
  65 \r
  66 Debugging the shell extension\r
  67 -----------------------------\r
  68 \r
  69 (This might be out of date)\r
  70 \r
  71 Since TortoiseGit is a shell extension it's not as easy to debug as\r
  72 normal applications. The TortoiseShell part is only a dll which is\r
  73 loaded by the windows explorer. So the first thing you need to do is:\r
  74 \r
  75 - add the following value to the registry:\r
  76   HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\DesktopProcess\r
  77   (REG_DWORD) = 1\r
  78   This will tell windows to start each explorer in a separate process\r
  79   instead of one single process.\r
  80 - register the TortoiseShell dll so that the windows explorer loads it.\r
  81   There are three files in the folder src\TortoiseShell with extension\r
  82   *.registry. Make a copy of those files and change the extension to\r
  83   *.reg. Then you have to edit those three files so that the paths in\r
  84   it reflects your source paths exactly. Now if you doubleclick on\r
  85   register.reg the debug version of the TortoiseGit.dll get's\r
  86   registered. registerrelease.reg registers the release version of the\r
  87   TortoiseGit.dll. Don't do it right now!\r
  88 - Start VS and load the TortoiseGit solution file. Set the\r
  89   TortoiseShell project as "startup project".\r
  90 - Close all running instances of windows explorer.\r
  91 - Now execute the register.reg file. Since you already closed all\r
  92   explorer windows you'll have to use the windows start button, then\r
  93   execute, enter the location of the reg file and hit enter. Since this\r
  94   is a lot of clicking I made a shortcut of those files in the\r
  95   quickstart on the taskbar.\r
  96 - Hit F5 in the VS IDE (or start debugging via menu). The first time\r
  97   you do that VST will ask you to enter an application to use with the\r
  98   TortoiseGit.dll - enter c:\windows\explorer.exe (or whatever path it\r
  99   is on your system).\r
 100 - Now you can set breakpoints and debug as you like.\r
 101 - Don't stop debugging by closing the explorer window - this sometimes\r
 102   leads to a locked dll and you can't compile/link the dll again until\r
 103   you have restarted. Always stop debugging with the command in the VS\r
 104   IDE (Shift-F5).\r
 105 - After debugging, execute the file deregister.reg. Do this always\r
 106   _immediately_ after debugging or you might get a locked dll.\r
 107 - while debugging, _never_ start another explorer instance or internet\r
 108   explorer or any other application which uses  explorer - this includes\r
 109   already running applications to open dialogs like "save as"!\r