As a product owner, my official build verifies symbol packages are complete

[maririos]

@dagood commented on Fri Dec 09 2016

Similar to verifying that packages are signed before publishing them, packages should be verified to have complete symbol packages.

Without this implemented, the worst case scenario (which has happened at least twice) is that a symbol package contains incomplete info or doesn't exist for a package that's released to the world. If nobody notices quickly enough to manually save the symbols (from the build machine or a temporary cpvsbuild share) the symbols become impossible to find.

---

@markwilkie commented on Thu Mar 22 2018

Moving to prodcon to make sure it's done

---

@dagood commented on Thu Mar 22 2018

Related: https://github.com/dotnet/core-eng/issues/2448 "Post-build symbol availability validation". That one's about making sure the symbols are available from the production endpoints, this one's about making sure the right symbols are included in build outputs at all.

[dagood]

Moved over the core-eng 2448 mentioned in my last comment to #173

[JohnTortugo]

AFAIU our current implementation of Publish makes a copy of the regular package and calls it a symbol package in case of absent symbol package:

arcade/src/Microsoft.DotNet.Arcade.Sdk/tools/Publish.proj

Line 59 in 040b796

<!--

[jcagme]

Yeah I think is the case

[dagood]

How do you see that affecting this issue?

[dagood]

Adding some more specific info on what makes a "complete" symbol package.

For every <id>.nupkg file a build produces, look for these files and make sure the associated files are in the <id>.symbols.nupkg symbol package:

• Managed <name>.dll or <name>.exe

  • The file itself
  • Portable PDB file <name>.pdb
  • Windows PDB file is not included in the symbol package, it does need to be published in some way however so availability validation is probably the right place to check for this.
    • In old infra, the portable PDB is converted on demand at upload time.
    • In new Arcade infra, the portable PDB is converted to Windows PDB during the build.

• Crossgen'd <name>.dll or <name>.exe

  • The file itself
  • NGEN PDB file <name>.ni.pdb

• Native <name>.dll, <name>.exe, <name>.so, <name>.dylib, <name>

  • The file itself
  • Symbol file associated with the extension/platform:
    • .dll, .exe => <name>.pdb
    • .so => <name>.so.dbg
    • Extensionless Linux binary => <name>.dbg
    • .dylib => <name>.dylib.dwarf
    • Extensionless macOS binary => <name>.dwarf

• coreclr.dll

  • In addition to the normal <name>.dll associations:
  • sos.dll
  • mscordbi.dll
  • mscordaccore.dll
  • mscordaccore_<platform>_<platform>_<buildnumber>.dll
    • "Long-name DAC"
    • E.g. mscordaccore_amd64_amd64_4.6.27317.07.dll
    • Build number must match coreclr.dll version info
    • The platforms are there to enable cross-debugging. I don't remember the order. In .NET Core situations they are currently always the same platform repeated.
  • sos_<platform>_<platform>_<buildnumber>.dll
    • "Long-name SOS"
    • Same verification as long-name DAC

If a file has any files associated with it, they must be in the same directory as the file in the symbol package. (This may only be actually needed for certain associations like long-name DAC/SOS, but I'm not sure.)

If a nupkg has no files that match the above, an associated symbol package isn't needed.

An extra step I'm not familiar with would be checking to make sure all pdb files have valid source-link info in them. This may be complicated with internal builds and security releases.

There will be exceptions, such as files that are redistributed in nupkgs that weren't built in the repo, where symbol publishing is handled by the original repo. Ideally Arcade can figure out what exceptions are expected, and if not that, the exceptions should be stored in the product repo.

---

The above steps can be run offline to validate that the symbol package is complete. Once the symbol package is uploaded to symbol servers, we need to then run availability validation which is tracked by #173.

[markwilkie]

Thanks @dagood !

[tmat]

Note that for managed code we will switch to the new .snupkg packages for symbols, once we have sufficient support in infrastructure. #1959

[dagood]

It looks like the nupkg and snupkg will need to be merged to create complete Msft-spec symbol packages, based on https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg#symbol-package-structure:

Files and folders with extensions other than PDB will be left out of the snupkg.

Symbol packages must have both the DLL/EXE and PDB.

[tmat]

Symbol packages must have both the DLL/EXE and PDB.

That was true for .symbols.nupkg, but those are pretty much obsolete for managed PDBs.
The future is snupkgs. No merging.

[dagood]

Is there any plan for how that's compatible with Microsoft symbol servers and various requirements?

Will repos that produce native bits and managed bits need to produce both symbol packages and snupkgs?

I'm likely out of the loop, but I want to make sure this doesn't fall through the cracks.

[JohnTortugo]

Closing this since now we have a short term solution (#2534) and another issue for a long term solution (dotnet/arcade-services#2465)