Compiler option for embedding source in debug builds not documented

[baldurk]

Description
The compiler option -Qsource_in_debug_module is not documented in -help where users are likely to look for it when trying to use debug info as generated by -Zi.

Steps to Reproduce
When building a module with separate debug info using -Zi -Fd ..., if -Qsource_in_debug_module is not specified then the debug info module doesn't have any source for the hlsl files in the debug metadata.

This flag is only needed if separate debug info is used - if the debug info is embedded in the module then the source is there as expected. The flag isn't documented anywhere though as far as I can tell, at least it's not mentioned in -help along with the other debug options - I'd expect it near -Qembed_debug.

$ dxc -Od -Zi a.hlsl -Qembed_debug -Fo a.dxbc -T cs_6_0
$ dxc -dumpbin a.dxbc | grep 'void main'
!38 = !{!"a.hlsl", !"RWByteAddressBuffer a : register(u0);\0D\0A\0D\0A[numthreads(1,1,1)]\0D\0Avoid main() {\0D\0A\09a.Store(0, uint(4));\0D\0A\09a.Store(128, float(4));\0D\0A\09a.Store(256, float4(4,5,6,7));\0D\0A\09a.Store(512, double(8));\0D\0A\09a.Store(768, double4(8,9,10,11));\0D\0A}\0D\0A"}
$ dxc -Od -Zi a.hlsl -Fd a.pdb -Fo a.dxbc -T cs_6_0
$ dxc -dumpbin a.dxbc | grep 'void main'
$ dxc -dumpbin a.pdb | grep 'void main'

Actual Behavior
Since the source is a big part of the value of the debug data I would expect the necessary flag to be documented in -help and in the documentation like SourceLevelDebuggingHLSL.rst.

Environment

• DXC version dxcompiler.dll: 1.7 - 1.7.2308.7 (69e54e2); dxil.dll: 1.7(101.7.2308.12)
• Host Operating System Windows 10 19045

[pow2clk]

This was a conscious decision made when the "slim PDB" flag -Zs was added. It's there for anyone desperate for the old behavior, but we want to deprecate it by making it hidden.

[baldurk]

To clarify are you saying that the only supported way to include source in debug info at all is either to use slim PDBs, or to embed the debug info in the shader blob itself? Is -Qembed_debug deprecated as well, or is its inclusion of source code deprecated?

That doesn't seem like a useful set of options to me as in my view there is definitely still value in having separate but complete debug info. If that's the case, why have the normal separate debug info at all? It has all of the extra information associated with debug info just not the source code to actually tie it up to. This effectively forces people who want that behaviour to compile with embedded debug, copy that out to the hashed debug location, and then strip the debug info out.

[baldurk]

Talking offline to @llvm-beanz he suggested I ping this issue again. I'd like to ask if you'd reconsider this decision. I don't think slim PDBs are strictly better than normal PDBs so I think there's significant value in having a way to generate normal PDBs with the source embedded rather than only the debug info itself.

For people who don't want to use slim PDBs I think it would be good to have a documented way of generating full PDBs. I would argue that it should be opt-out to include the source rather than opt-in, but I think documenting and making clear the option would be useful regardless.