Change the naming convention for debug symbol files on Windows to avoid collisions (e.g. java.exe/java.dll -> java.pdb)

[Frederic Thevenet]

Hi,

I would like to submit the following proposal for discussion on this 
list: changing the naming convention for debug symbol files on Windows, 
in order to avoid collisions.

When building OpenJDK on Windows using 
"--with-native-debug-info=external", the resulting debug symbols are 
saved in files located in the same folder as the corresponding 
executable or library and named by swapping the extension ".exe" or 
".dll" for a ".pdb" one (or "diz" if option 
"--with-native-debug-info=zipped" is used).

While this is indeed a common convention on Windows - and the default 
configuration in Visual Studio - this has the unfortunate side effect of 
producing colliding paths in the event of an exe and a dll file sharing 
the same target folder and file name, save for the extension.
In the case of OpenJDK, there are three occurrences (that I am aware of) 
where this happens:  "bin\java.exe" and "bin\java.dll" resolve to the 
same "bin\java.pdb" for their symbols, as do "jimage.exe/jimage.dll" and 
"jpackage.exe/jpackage.dll", meaning both set of debug information 
cannot naturally coexist while strictly adhering to the rule.
(NB: Builds for unix-like platforms are not affected by this, due to a/ 
the fact that libraries and launchers are not located in the same 
folder, b/ the radical for executables and libraries typically differ, 
e.g. java / libjava)

Since it is generally admitted that the debug symbols for the libraries 
contain are likely to be more useful that those for the launchers,  
specific build logic has to be added in several places to ensure those 
symbols are always prioritized [1][2].

This is nonetheless a sub-optimal situation, since:
   - it leaves out entirely the debug info for java.exe, jpackage.exe 
and jimage.exe
   - It requires special case handling in the build logic to guaranty 
consistency in what symbols are kept, which needs to be updated each 
time a new occurrence is introduced.
   - It is overall surprising to developers unaware of this situation 
and likely to raise suspicion of a bug[3].

One way to avoid all the issues above, would be to adopt a naming 
strategy for the pdb files that does not incur a risk of collision; for 
instance by keeping the original extension in the final name, e.g. 
"jvm.dll" -> "jvm.dll.pdb" instead of "jvm.pdb" (and 
"jvm.dll.stripped.pdb" for stripped symbols if 
"--with-external-symbols-in-bundles=public" is used, "jvm.dll.diz" for 
"--with-native-debug-info=zipped").

According to my initial findings, the changes to accomplish this are 
quite straight forward and easy to circumscribe to the Windows build [4].

Also, I have verified that the ".pdb" files with the new names are 
recognized by the Windows debugger in the same way as the old one; i.e. 
it requires no extra configuration steps to tell the debugger where to 
find the right symbol files [5].

I'm looking forward to your feedback on this proposal.

Thanks,

[1] 
https://github.com/openjdk/jdk/blob/a564d436c722f14041231158f21c4ad3a2f6a3a5/make/Images.gmk#L277
[2] 
https://github.com/openjdk/jdk/blob/a564d436c722f14041231158f21c4ad3a2f6a3a5/make/CreateJmods.gmk#L84
[3] https://bugs.openjdk.org/browse/JDK-8263356
[4] 
https://github.com/fthevenet/jdk/commit/877a3db829e4b3bba2bef05950e22de7ed89e3f8
[5] The naming used at the moment is the one commonly used on Windows 
but the name of pdb file can be whatever; it is in fact stored within 
the PE header of the artifact, which is how the debugger knows how to 
match them. See 
https://polystream.com/behind-the-curtain-understanding-the-magic-behind-loading-symbols-in-visual-studio/

-- 
Frederic Thevenet
Senior Software Engineer - OpenJDK
Red Hat France<https://www.redhat.com>
BAF5 C2D2 0BE0 1715 5EE1 0815 2065 AD47 B326 EB92