Write the managed ilasm PDB to a separate file, as native ilasm does

[pcshrosbree]

In #135212, @jkotas pointed out that native ilasm is being replaced by the C# rewrite in src/tools/ilasm and suggested fixing issues there. I listed three PDB differences between the managed and native ilasm, and @jkoritzinsky confirmed that they are unintended and should be fixed in managed ilasm. This PR fixes them.

Changes

	Before	After
-DEBUG / -PDB	PDB embedded in the image (EmbeddedPortablePdb entry)	PDB written to <output>.pdb beside the output, not embedded, as native ilasm
.line without -DEBUG or -PDB	embedded PDB produced	no PDB and no debug directory, as native ilasm; .line is still parsed and validated
CodeView path	always assembly.pdb	full path of the PDB file, as native ilasm; under -DET only its file name (Min.pdb), a deliberate difference that follows the linker's /PDBALTPATH:%_PDB%

• Debug directory. It is CodeView, then PdbChecksum, then, with -DET, Reproducible: the same entry types in the same order as native ilasm.
  • The checksum is SHA-256 of the PDB with its 20-byte id zeroed (PE-COFF.md).
  • It is the hash the PortablePdbBuilder id provider computes, so under -DET the PDB id and the checksum come from one hash.
• No PDB, no debug directory. An image built without a PDB has no debug directory, with or without -DET. ManagedPEBuilder adds a Reproducible-only directory to a deterministic image when it is given none. A small ILAssemblerPEBuilder subclass, which the vtfixup/export builder also derives from, clears a debug directory with no entries.
• Library and CLI. PDB generation does not touch the file system.
  • CompilationResult.PortablePdb returns the PDB bytes, the new Options.PdbFilePath supplies the CodeView path, and the CLI writes the file.
  • Library callers that don't set PdbFilePath get the output file name with a .pdb extension, or assembly.pdb.
• File output is split in two: OutputWriter in ILAssembler works on streams and makes the decisions below, and OutputFileWriter in ilasm supplies the files:
  • Write order. It writes and closes the image, then writes the PDB to a new temporary file in the same directory and renames it over <output>.pdb, so <output>.pdb never holds a partial PDB. If the PDB cannot be written, the run fails with the new image beside the previous PDB, and deleting the temporary file is attempted.
  • Stale PDBs. After writing an image without a PDB, it deletes an existing <output>.pdb only if it belongs to the image that was replaced, that is, if the previous image's CodeView entry names that PDB's id. Any other file is kept, including when the previous output is not a PE image it can read (a COFF object file or a file over 2 GB, for example), and an output that is itself named like its PDB is never deleted. A PDB that cannot be deleted is left in place without failing the run. When assembly fails and produces no output, it writes and deletes nothing; with -ERR, an image produced despite errors is written and its PDB is handled as for a successful assembly.
    • Native ilasm deletes <output>.PDB whenever it writes no PDB, including when assembly fails. I dropped that deliberately, because it can remove a PDB that ilasm did not write or that belongs to an image that was not replaced.
    • On Linux native deletes <output>.PDB, so it has not been removing .pdb files there.
  • Name collisions. If the PDB path would be the output path (-OUTPUT=Min.pdb -DEBUG), it reports an error and writes nothing, where native ilasm overwrites the image with the PDB. The comparison ignores case on Windows and macOS.
• Switches. --debug-mode alone produces a PDB, as it already implied --debug for the DebuggableAttribute. -PDB still adds no DebuggableAttribute of its own.
• Docs.
  • The options have doc comments.
  • The DebugMode.Impl docs said it enables Edit and Continue. IMPL is 0x103, Default | IgnoreSymbolStoreSequencePoints | DisableOptimizations, and the docs now say so.
  • The --debug-mode help says what the modes do to the JIT.

Round-trip harness (needed for this PR to merge).

• src/tests/Common/CLRTest.Jit.targets checked PDB determinism by assembling with -DEBUG -output=<name>.pdb and hashing that file. That works with native ilasm only because the PDB overwrites the image.
• Managed ilasm now refuses that output path, so the managedilasmroundtrip lane would fail.
• The third commit assembles that step to IL-RT/<name>.pdbcheck.dll and hashes both that image and the .pdb beside it, which both ilasms write. The previous managed run had also checked the -DEBUG image, by hashing it with the PDB embedded.
• I ran the changed step by hand with native and managed ilasm. Both repeat byte-identically, and a run without -DET fails the image comparison, and with the image comparison removed fails the PDB comparison, as it should. I could not run the lanes themselves. In the round-trip lane, reassembling a non-debug test assembly without -DEBUG now removes the compiler's <name>.pdb, which belongs to the replaced image; the reassembled image has no debug directory, so nothing reads it, and the previous step overwrote that file anyway.

Determinism. With -DET the CodeView entry records only the PDB's file name, so the same input assembled to outputs of the same name in different directories gives byte-identical images and PDBs (native ilasm records the full path in both modes; this follows the linker's /PDBALTPATH:%_PDB% convention instead).

Remaining differences from native ilasm:

• PdbChecksum entry timestamp: 0 in managed (DebugDirectoryBuilder), the PDB stamp in native. The managed entry is new in this PR.
• Nondeterministic PDB stamp: the constant 0x04030201 in managed, the clock in native.
• -DET PDB id: the PDB content hash in managed, the metadata hash in native.
• -OUTPUT=a.b/Min: native writes a.pdb in the parent directory; managed writes a.b/Min.pdb. That naming is deliberate.
• CodeView path under -DET: the PDB's file name in managed, its full path in native. That is deliberate (see Determinism above).
• Stale PDB removal: the ownership rule above, versus native's unconditional <output>.PDB deletion.
• PDB content: managed has no local scopes, uses one document per method, and does not record the .il source as a document.
• Netmodules: native emits the DebuggableAttribute on AssemblyAttributesGoHere; managed emits it only with .assembly.

Testing (Linux x64)

• ILAssembler.Tests: 1216 before; 2124 at commit 1, 2332 at commits 2 and 3, 2344 at commit 4, 2366 at commits 5 and 6, 2374 at commit 7, and 2379 at commit 8, all passing on Linux; on Windows two file-system tests skip, five symbolic-link tests skip unless the process can create symbolic links, and the relative-output test skips if the temporary directory is on another drive than the working directory.

  • Unit tests read the PDB from the compilation result. They pin:

    • the entry order, with and without -DET;
    • the CodeView path, its fallback, and its id;
    • the checksum, against the PDB with its id zeroed;
    • no PDB from .line alone;
    • no debug directory or debug data without a PDB, including through the vtfixup/export builder;
    • -PDB without a DebuggableAttribute;
    • deterministic PDB and image bytes.

  • OutputWriterTests tests the output writer on in-memory streams, without the file system. It covers:

    • the write order, including closing the image before touching the PDB (an injected close failure);
    • which existing PDB it deletes, including when the replaced output is a COFF object, longer than 2 GB, or cannot be opened;
    • the refusal to write a PDB over the output.

  • OutputFileWriterTests covers the file side: the PDB path, the temporary file and rename, deletion, and the case rule.

  • Seeded theories check the same rules over generated programs and option combinations (800 cases). They also check the file writer over an enumeration of output names and pre-existing output and PDB states (270 cases). Each case is named by its index and description.

  • CommandLinePdbFileTests runs the command line in process on IL sources in a temporary directory (27 cases). It covers:

    • the PDB beside the output and its CodeView entry;
    • under -DET, a CodeView entry with only the PDB's file name, for absolute and relative output paths, and the PDB found beside the image from that name;
    • the entry order and the checksum;
    • no PDB without a switch, with .line and with -DET;
    • -PDB without a DebuggableAttribute;
    • stale-PDB replacement and deletion, and an unrelated PDB kept;
    • failed builds;
    • -ERR with a recoverable error;
    • the refusal of an output named like its PDB;
    • byte-identical -DET repeats, and byte-identical -DET images and PDBs across two output directories.

    The cases that ran native ilasm as a control were dropped when these tests moved out of src/tests/ilasm.

  • I ran 59 selected mutations, one at a time: 19 in the compiler (checksum, entry order, gating), 32 in the two output writers and 8 in the command line. 58 were detected. The survivor removes a file-existence check before opening a file; it is equivalent for stable files, because a missing file raises an IOException that the library counts as no id.

• I ran the built CLI end to end and compared it with native ilasm, both as built from this branch and with Fix ilasm PdbChecksum and the PDB ID under -DET #135212's fix. I checked the files written, the entries, the checksum, byte-identical -DET repeats, and stale-PDB handling.
• src/tests/ilasm/PortablePdb against managed ilasm: 0/10 before, 4/10 after.
  • Both TestPortablePdbDebugDirectory cases now pass.
  • The six failures have three causes, all PDB content this PR does not touch: local scopes (4 cases), a method whose sequence points span two documents (TestDocuments1), and the .il source as a document (TestPortablePdbDocuments). Fixes for those are in progress separately and will follow as their own PRs.

Not run: Windows, macOS, Arm64, the round-trip lanes, or the full src/tests suite. The ilasm pipeline runs on this PR and covers the round-trip lanes on eight platforms and ILAssembler.Tests on Windows x64.

Questions:

• Is ImmutableArray<byte>? CompilationResult.PortablePdb the shape you want, or ImmutableArray<byte> with IsDefault?
• Would you rather have an option in System.Reflection.Metadata for "no debug directory" than the ILAssemblerPEBuilder subclass? ManagedPEBuilder has no public way to decline its default Reproducible entry.
• Following the review, the CodeView entry now holds only the PDB's file name under -DET, and its full path otherwise.
• Is deleting <output>.pdb only when it belongs to the replaced image the behaviour you want?
• Is the --debug-mode help wording right?

Note

This change was prepared with AI assistance (Anthropic Claude and OpenAI Codex) under my direction. AI agents wrote the code and ran the build and tests on my machine. I reviewed the change before posting.

[azure-pipelines]

Azure Pipelines:
Successfully started running 5 pipeline(s).
11 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[dotnet-policy-service]

Tagging subscribers to this area: @JulieLeeMSFT, @dotnet/jit-contrib
See info in area-owners.md if you want to be subscribed.

[jkoritzinsky]

Instead of adding tests under src/tests/ilasm, please add the new tests under ILAssembler.Tests. That test suite is significantly cheaper to run and is the way forward for our testing for managed ilasm.

[pcshrosbree]

Thanks, both are done. The output writer is now two types: OutputWriter in ILAssembler works only on streams, through a small IOutputStreams interface, and makes every decision (write order, which existing PDB to delete, and the refusal to write a PDB over the output), all unit-tested on MemoryStreams in OutputWriterTests; OutputFileWriter in ilasm supplies the files, writes the PDB through a temporary file and a rename, and does the deletion. The library types are public because ILAssembler has no InternalsVisibleTo and the tool already calls only its public types (DocumentCompiler, CompilationResult); I can switch to InternalsVisibleTo if you prefer. The end-to-end tests moved from src/tests/ilasm into ILAssembler.Tests as CommandLinePdbFileTests, which links Program.cs and runs the command line in process against a temporary directory, so src/tests/ilasm matches main again. I dropped the rows that ran native ilasm as a control, since native ilasm has no place in ILAssembler.Tests. Linking Program.cs also needed <GenerateProgramFile>false</GenerateProgramFile> in the test project; I'm happy to revisit either choice.

[Copilot]

🟡 Changes recommended

An output symlink targeting its PDB path can cause a successful run to lose the generated image.

2 open findings

• Prevent symlinked output from overwriting the image with the PDB · New
• Skip the platform-specific test on Windows instead of passing · New

What changed in this PR

Updates managed ilasm to emit separate Portable PDB files and align debug-directory behavior with native ilasm.

Changes:

• Returns and writes standalone PDB data with CodeView/checksum entries.
• Adds safe PDB replacement and stale-PDB handling.
• Expands unit, generated, CLI, and round-trip tests.

File	Description
SourceDirectiveTests.cs	Updates source-directive PDB tests.
OutputWriterTests.cs	Tests stream-based output decisions.
OutputFileWriterTests.cs	Tests filesystem output behavior.
ModuleTests.cs	Reads standalone module PDBs.
ILAssembler.Tests.csproj	Links CLI output components.
PdbGeneratedCaseTests.cs	Adds generated PDB/output tests.
PdbCaseGenerator.cs	Generates deterministic test cases.
DocumentCompilerTestHelpers.cs	Adds standalone-PDB helpers.
CompilerOptionsTests.cs	Tests PDB options and directories.
CommandLinePdbFileTests.cs	Adds end-to-end CLI coverage.
AssemblyTests.cs	Updates deterministic PDB tests.
VTableExportPEBuilder.cs	Uses the shared PE builder.
OutputWriter.cs	Implements stream-based output handling.
Options.cs	Documents and adds PDB path options.
ILAssemblerPEBuilder.cs	Suppresses empty debug directories.
CompilationResult.cs	Exposes generated PDB bytes.
GrammarActions.BuildImage.cs	Builds standalone PDBs and references.
Program.cs	Writes image and PDB outputs.
OutputFileWriter.cs	Implements filesystem output handling.
IlasmRootCommand.cs	Clarifies debug-mode help.
README.md	Documents PDB behavior.
CLRTest.Jit.targets	Updates round-trip determinism checks.

🧠 Review effort: Balanced

[jkoritzinsky]

One more request. Otherwise looking good to me so far.

[jkoritzinsky]

One last change, then this will be good to merge.

[pcshrosbree]

Rebased onto main after #135115 landed (now 09d4a59): the only differences are context lines in Program.cs and the position of a test constant in CompilerOptionsTests.cs; the code is unchanged.