This project is read-only.


Simplify symbol package creation



I love the ability to push packages and symbol packages to nuget and with a simple command.

However, creating symbols packages is overly complicated right now. The project file approach (.csproj) is a neat trick, but not practical except in the most basic situation (no support for multiple projects, multiple target frameworks, external builds,
etc). There needs to be a streamlined approach for building .symbols.nupkg companion packages from a given nuspec file. I do not want to use the conventional folders approach to specifying my files, as it seems tedious to have to move files around
the filesystem, instead of referencing them where they are in my source tree.

Currently, this requires the following process:

create a single nuspec file, it uses file elements to specify all of the files that will be included in the library and symbol packages.
call nuget pack myspec.nuspec rename the created myspec.1.0.0.nupkg to myspec.1.0.0.symbols.nupkg call nuget pack myspec.nuspec -Exclude ***.pdb -Exclude ***.cs
I now have myspec.1.0.0.nupkg and myspec.1.0.0.symbols.nupkg.

This seems like a common scenario that should be baked in somehow. Currently, the -Symbols option for the pack command is only valid when building from a package. How about we allow use of the -Symbols option with .nuspec files, and give it the following

build the source package, and give it the .symbols.nupkgs name build the lib package, automatically excluding all pdbs, and the entire /src target folder

If doing 2 builds would be too complicated in a single command, maybe -Symbols option just does step 1, and a -NoSource option does step 2.

Are there any other ideas out there on how to support symbol package creation from a nuspec file?
Closed Jun 8, 2011 at 4:42 AM by aldion
  • -Symbols creates 2 packages (.nupkg / .symbols.nupkg)
    • .symbols has the regular content plus debug infor : pdb as well as src : .cs/.vb/.fs
  • with nuspec that already include those files
    note: filed #1163, errors in some cases.
  • package created with nuspec only, nuspec with csproj or vbproj or fsproj
  • without -Symbols, same behavior
  • help for -symbols
  • verbose output makes sense with -symbols
  • exclude still works with symbols (exampe : exclude source file)
  • -Properties (example w/ /unsafe)
  • error cases (no nuspec, nuspec not found, project not built and no -symbols, ...)


TripleEmcoder wrote May 20, 2011 at 7:43 PM

Let me restate here how we see things at SymbolSource. The nuget pack command should behave similarly when invoked with a csproj and a nuspec file. So, if you invoke it without the -Symbols option, it could build a regular package as always:
  • either from the csproj file
  • or according to the files section of the nusped file,
  • or by convention if that section does not exist.
Specifying -Symbols should cause build two packages and automatically decide which items go into which.

The binary .nupkg should then contain only dlls, xmldocs, tools and other content, whereas the .symbols.nupkg should contain dlls, pdbs, also xmldocs (this one isn't actually required, but if we standarize on this behaviour, there are some nice things that we have in store for the and of course sources.

How these should be specified in the files section, when not using packaging by convention, I'm not sure. Consider this example from NuGet docs, extended a bit:
<file src="bin\Debug*.dll" target="lib" />
<file src="bin\Debug*.pdb" target="lib" />
<file src="***.cs" target="src" />

Here I added a target of "src". Should this target be stated explicitly? Is there a scenario where you put *.cs files as content rather as the actual sources? Probably yes, as you could want to include examples. Do you have any other ideas?

joshuaflanagan wrote May 21, 2011 at 1:54 AM

Ok, so you design your package to include PDBs and all source (using either the conventional folders or the file elements in nuspec). If you do not pass the -Symbols options, it will include everything you specified in a single package (no magic, no surprises). If you do pass the -Symbols option, it will create 2 packages, stripping out pdb's and src from the lib package, and stripping out content from the symbols package.

I can work on this if nobody else has started.

davidebbo wrote May 21, 2011 at 2:45 AM

Yep, I think that's the idea! And no one has started on it, so feel free to play around with it :)

TripleEmcoder wrote May 21, 2011 at 6:44 PM

Great! Although I think you may want to strip out sources also for the regular package (without -Symbols).

joshuaflanagan wrote May 21, 2011 at 7:11 PM

I disagree. If you do not specify -Symbols, you should have complete control over what is included in your package.

TripleEmcoder wrote May 21, 2011 at 7:40 PM

Yes, you're right. But in that case you can't put any sources in the files section, correct? Putting them in will force you to always use -Symbols, otherwise you will get sources packaged into a regular package, which you normally don't want. I thought this solution could be universal in the way that you write your nuspec once to support both scenarios and then decide what to build on the command-line. Perhaps we're talking about different cases?

davidebbo wrote May 21, 2011 at 7:54 PM

Yep, that's kind of the one sticky point right now. You really don't want the sources to end up in the regular package. Of course, there is the possibility that someone wants a src folder that is not related to this feature, though that seems unlikely.

But anyway, aside from this one point, it seems we're all in agreement.

joshuaflanagan wrote May 21, 2011 at 11:00 PM

You definitely only want to write your nuspec once, and you definitely want to be able to put sources in the file section. On that, we are in full agreement.
I think the key point you may be missing is that the -Symbols flag means "I intend to support the symbol server scenario - please generate a proper lib package and a proper source package". It does not just mean "generate a symbols package". If you do not provide the -Symbols flag, it means you do not care about the symbol server scenario, and you will take responsibility for including the files you want. If you include source files, it means you want source files. If you did not want source files in your lib package, and you did not care about the symbol server scenario (hence no -Symbols flag), you would not include source files in your files section.

TripleEmcoder wrote May 21, 2011 at 11:38 PM

What I was refering to is a case when you write your nuspec once, and want to alternate between "nuget pack" and "nuget pack -Symbols". Without changing nuspec, sometimes do "nuget pack -Symbols" to do the full thing for general publishing, then do "nuget pack" just for a local test build, then again "nuget pack -Symbols" to publish a fixed version. I am not saying that this scenatio makes sense, I just want to make sure that you are aware of the implications if someone does deside to use it that way :)

joshuaflanagan wrote May 22, 2011 at 12:48 AM

Ok, if that becomes a concern (filtering source when not specifying -Symbols), we could potentially add a -NoSource or -NoSymbols option which will make use of the same filtering logic.

joshuaflanagan wrote May 22, 2011 at 12:51 AM

I've submitted a pull request that adds basic support for what we've described:

I made an initial guess at what to exclude from the symbols package, but it is very easy to extend.

Haacked wrote May 23, 2011 at 10:36 PM

Pranav, can you review the pull request?

pranavkm wrote May 25, 2011 at 9:16 AM

Fixed with changeset 2e7df0e9ae42

TripleEmcoder wrote May 26, 2011 at 10:30 AM

Just tested the CI build with this feature. Everything works as expected, thanks a lot!