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 have logged a ticket over on JBS for this: 
https://bugs.openjdk.org/browse/JDK-8317510

The associated PR is: https://github.com/openjdk/jdk/pull/16039

Thanks,

On 02/10/2023 20:21, Frederic Thevenet wrote:
> 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