/win32/shellext/README.txt

  1== C++ Shell Extension ==
  2
  3=== Installing build tools ===
  4
  5Get the gratis "Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1"
  6from microsoft.com.
  7
  8You can install from web or download an ISO image, burn a DVD and install from
  9that. Make sure you get the correct download for the Windows version you want to
 10use for building: the x86 (32 bit) download won't install on 64 bit platforms.
 11
 12The SDK contains the C++ compiler, linker, nmake, and header files, which is all
 13we need to build the x86 (32 bit) and 64 bit variants of the shell extension.
 14
 15The compiler and linker can build both the 32 bit and the 64 bit targets, no matter
 16if you install the 32 bit (x86) or the 64 bit version of the SDK. In other words:
 17it can cross compile.
 18
 19The SDK is compatible with Visual C++ 2005 and 2008 (including express versions).
 20But Visual C++ is *not* needed to build the shell extension!
 21
 22Leave all install options at their defaults.
 23
 24(see also C:\Program Files\Microsoft SDKs\Windows\v7.0\ReleaseNotes.Htm
 25section "4.4.2 Setting Build Environment Switches" after install)
 26
 27
 28=== Building the x86 (32 bit) target ===
 29
 30Open a command shell and cd into win32/shellext of the TortoiseHg sources.
 31
 32Copy/paste the following line (including the double quotes) into that shell
 33
 34cmd.exe /E:ON /V:ON /K "C:\Program Files\Microsoft SDKs\Windows\v7.0\Bin\SetEnv.cmd" /xp /x86 /Release
 35
 36and execute it (see ReleaseNotes.Htm).
 37
 38This should show the following in your shell
 39
 40'''
 41Setting SDK environment relative to C:\Program Files\Microsoft SDKs\Windows\v7.0.
 42Targeting Windows XP x86 RELEASE
 43'''
 44
 45Then execute
 46
 47  nmake /f Makefile.nmake clean
 48
 49followed by
 50
 51  nmake /f Makefile.nmake
 52
 53Which should go like this:
 54
 55'''
 56$ nmake /f Makefile.nmake clean
 57
 58Microsoft (R) Program Maintenance Utility Version 9.00.30729.01
 59Copyright (C) Microsoft Corporation.  All rights reserved.
 60
 61        del *.obj *.dll *.exe *.lib *.exp *.manifest
 62
 63$ nmake /f Makefile.nmake
 64
 65Microsoft (R) Program Maintenance Utility Version 9.00.30729.01
 66Copyright (C) Microsoft Corporation.  All rights reserved.
 67
 68        cl /nologo /Ox /W2 /EHsc /MT /DAPPMAIN /DTHG_DEBUG /c TortoiseUtils.cpp Direntry.cpp Directory.cpp Winstat.cpp ThgDebug.cpp InitStatus.cpp CShellExtCMenu.cpp CShellExtOverlay.cpp IconBitmapUtils.cpp Registry.cpp ShellExt.cpp StringUtils.cpp SysInfo.cpp dirstate.cpp Winstat64.cpp Dirstatecache.cpp DirectoryStatus.cpp Thgstatus.cpp QueryDirstate.cpp
 69TortoiseUtils.cpp
 70Direntry.cpp
 71Directory.cpp
 72Winstat.cpp
 73ThgDebug.cpp
 74InitStatus.cpp
 75CShellExtCMenu.cpp
 76CShellExtOverlay.cpp
 77IconBitmapUtils.cpp
 78Registry.cpp
 79ShellExt.cpp
 80StringUtils.cpp
 81SysInfo.cpp
 82dirstate.cpp
 83Winstat64.cpp
 84Dirstatecache.cpp
 85DirectoryStatus.cpp
 86Thgstatus.cpp
 87QueryDirstate.cpp
 88Generating Code...
 89        link /OUT:THgShell.dll /nologo /INCREMENTAL:NO /MANIFEST shlwapi.lib gdiplus.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /DLL /DEF:ShellExt.def TortoiseUtils.obj Direntry.obj Directory.obj Winstat.obj
 90ThgDebug.obj InitStatus.obj CShellExtCMenu.obj CShellExtOverlay.obj IconBitmapUtils.obj Registry.obj ShellExt.obj StringUtils.obj SysInfo.obj dirstate.obj
 91Winstat64.obj Dirstatecache.obj DirectoryStatus.obj Thgstatus.obj QueryDirstate.obj
 92   Creating library THgShell.lib and object THgShell.exp
 93        mt -nologo -manifest THgShell.dll.manifest -outputresource:"THgShell.dll;#2"
 94'''
 95
 96This should produce the file THgShell.dll, which contains the 32 bit variant of the
 97shell extension.
 98
 99
100=== Building the 64 bit target ===
101
102Open a command shell and cd into win32/shellext of the TortoiseHg sources.
103
104Copy/paste the following line (including the double quotes) into that shell
105
106cmd.exe /E:ON /V:ON /K "C:\Program Files\Microsoft SDKs\Windows\v7.0\Bin\SetEnv.cmd" /xp /x64 /Release
107
108and execute it (see ReleaseNotes.Htm).
109
110This should show the following in your shell
111
112'''
113Setting SDK environment relative to C:\Program Files\Microsoft SDKs\Windows\v7.0.
114Targeting Windows XP x64 RELEASE
115'''
116
117Then execute
118  
119  nmake /f Makefile.nmake clean
120  
121followed by
122
123  nmake /f Makefile.nmake
124
125Which should go like this:
126
127'''
128$ nmake /f Makefile.nmake clean
129
130Microsoft (R) Program Maintenance Utility Version 9.00.30729.01
131Copyright (C) Microsoft Corporation.  All rights reserved.
132
133        del *.obj *.dll *.exe *.lib *.exp *.manifest
134
135$ nmake /f Makefile.nmake
136
137Microsoft (R) Program Maintenance Utility Version 9.00.30729.01
138Copyright (C) Microsoft Corporation.  All rights reserved.
139
140        cl /nologo /Ox /W2 /EHsc /MT /DAPPMAIN /DTHG_DEBUG /c TortoiseUtils.cpp Direntry.cpp Directory.cpp Winstat.cpp ThgDebug.cpp InitStatus.cpp CShellExtCMenu.cpp CShellExtOverlay.cpp IconBitmapUtils.cpp Registry.cpp ShellExt.cpp StringUtils.cpp SysInfo.cpp dirstate.cpp Winstat64.cpp Dirstatecache.cpp DirectoryStatus.cpp Thgstatus.cpp QueryDirstate.cpp
141TortoiseUtils.cpp
142Direntry.cpp
143Directory.cpp
144Winstat.cpp
145ThgDebug.cpp
146InitStatus.cpp
147CShellExtCMenu.cpp
148CShellExtOverlay.cpp
149IconBitmapUtils.cpp
150Registry.cpp
151ShellExt.cpp
152StringUtils.cpp
153SysInfo.cpp
154dirstate.cpp
155Winstat64.cpp
156Dirstatecache.cpp
157DirectoryStatus.cpp
158Thgstatus.cpp
159QueryDirstate.cpp
160Generating Code...
161        link /OUT:THgShell.dll /nologo /INCREMENTAL:NO /MANIFEST shlwapi.lib gdiplus.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /DLL /DEF:ShellExt.def TortoiseUtils.obj Direntry.obj Directory.obj Winstat.obj
162ThgDebug.obj InitStatus.obj CShellExtCMenu.obj CShellExtOverlay.obj IconBitmapUtils.obj Registry.obj ShellExt.obj StringUtils.obj SysInfo.obj dirstate.obj
163Winstat64.obj Dirstatecache.obj DirectoryStatus.obj Thgstatus.obj QueryDirstate.obj
164   Creating library THgShell.lib and object THgShell.exp
165        mt -nologo -manifest THgShell.dll.manifest -outputresource:"THgShell.dll;#2"
166'''
167
168This should produce the file THgShell.dll, which contains the 64 bit variant of the
169shell extension.
170
171
172=== Testing ===
173To install the new THgShell.dll for testing, rename the THgShellx86.dll in
174"C:\Program Files\TortoiseHg" to something else (e.g. THgShell-01.dll), then copy the newly built
175THgShell.dll to "C:\Program Files\TortoiseHg\THgShellx86.dll" and restart explorer.exe
176(logout/login will do as well).
177
178For x64 systems, the dll is instead located in
179"C:\Program Files\Common Files\TortoiseHg\ThgShellx64.dll".
180
181See
182http://www.addictivetips.com/windows-tips/how-to-restart-explorer-exe-process-properly-in-windows-xp-and-vista/
183for properly restarting explorer (in case you don't want to do a logout/login).
184Of course, simply killing explorer.exe with the task manager and restarting it will work too
185(you might loose some settings changes you might have done in explorer though).
186
187The shell extension emits trace output (TDEBUG_TRACE macro calls in the sources). This output
188can be captured by using for example the tool **DebugView** from Microsoft sysinternals (see 
189http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx).
190
191The debug output must be enabled in the registry. Double click the file
192"DebugShellExt.reg" and restart explorer.
193
194Example output (copied via clipboard):
195
196{{{
197[3504] [THG] findHgRoot(W:\xxx2\aa): hgroot = 'W:\xxx2' (found repo)
198[3504] [THG] Dirstatecache::get: lstat(W:\xxx2\.hg\dirstate) ok 
199[3504] [THG] DirectoryStatus::read(W:\xxx2): done. 2 entries read
200[3504] [THG] HgQueryDirstate: relbase = ''
201[3504] [THG] HgQueryDirstate: basedir_status = M
202}}}
203
204Another very helpful tool is sysinternals **Autoruns** 
205(http://technet.microsoft.com/en-us/sysinternals/bb963902.aspx ).
206This can be used to explore the registration of the extension. Use the tab "Explorer"
207to see the shell extensions registered.
208Recommended setting is "Hide Microsoft Entries" in menu "Options"
209
210
211=== TortoiseOverlays shim ===
212The TortoiseHg shell extension uses the common TortoiseOverlays package shared with
213other Tortoise projects (TortoiseSVN, TortoiseBZR, etc.).
214
215The sources for the TortoiseOverlays project can be found at 
216http://tortoisesvn.tigris.org/svn/tortoisesvn/TortoiseOverlays/
217(use user: "guest", no password).
218
219
220=== Issues ===
221* #324 - Question mark overlays are missing on Windows 7