NuGet Docs: Improve documentation on creating native packages

[Mike Jones]

NuGet Product Used

Other/NA

Product Version

N/A

Worked before?

No response

Impact

None

Repro Steps & Context

Ported from NuGet Docs, where we are closing issues.
Opener: KraigB

Information in the existing topic is sketchy, and there are questions, see https://docs.microsoft.com/en-us/nuget/create-packages/native-packages#comments-container.

Request: "Needs more details of what package structures need to be and links to other reference material. "

Older issues:
#1508
#3027

Additional customer feedback:

Needs more details of what package structures need to be and links to other reference material.
I need to download a package. But nowhere I can do this.
More information about how to actually create a native package (use CoApp or not?)
It's painfull to create even a simple NuGet native package. Writing the props/targets files is just like the hell (it should be generated like with CoApp). Someone at Microsoft has pointed me on https://github.com/Microsoft/vcpkg (great but) the NuGet package stuff is just for local use (it's a bridge on the native files); no way to create a standalone package for publishing on the official repository :-(.
How would the creation of the nuspec file and the packaging look like? At the moment, when creating the nuspec (via nuget spec) and package afterwards (via nuget pack) nuget (v 3.5) just takes everything that sits inside my project folder and packages that. The assembly is missing etc. The CoApp project is dead and I haven't found anything on the roadmap for nuget (https://github.com/NuGet).

COMMENTS
from @kraigb
See also https://github.com/MicrosoftDocs/mvp-hackadoc-2018/issues/43

COMMENTS
from @ras0219-msft
no way to create a standalone package for publishing on the official repository :-(.

Take a look at our export command [1][2].

[1] https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/
[2] https://github.com/Microsoft/vcpkg/blob/d80dd5cbc777ce765c2d6b78d7c485fdf05f284b/docs/users/integration.md#export

COMMENTS
from @kraigb
What we really need is someone familiar with the process using vcpkg to draft a walkthrough that demonstrates the whole process of creating a native package. That expertise unfortunately does not seem to exist within the NuGet team. I can provide editing help and bringing the draft up to docs quality. Just create a branch with the work in it and we can go from there.

COMMENTS
from @kraigb
Also addres https://github.com/NuGet/docs.microsoft.com-nuget/issues/190, https://github.com/NuGet/docs.microsoft.com-nuget/issues/592, and https://github.com/NuGet/docs.microsoft.com-nuget/issues/600.

COMMENTS
from @ericstj
Just hit this myself when trying to tell folks to use nativeassets. Can we please get docs for this feature that's been around for 2 years now? /cc @jainaashish @rrelyea

COMMENTS
from @Mizux
my 2 cents for "Building a cross-platform .NetStandard2.0 package with native dependencies" (only using dotnet/cli and modern .csproj)

I add my own way to do it there https://github.com/NuGet/docs.microsoft.com-nuget/issues/1013#issuecomment-414930782
And you can found a full example project in https://github.com/Mizux/dotnet-native (Documentation on the way)

Still, waiting for the official documentation !!!

COMMENTS
from @jjpepper
@kraigb that's not really correct. We don't really need anything vcpkg specific here, someone might be building in linux and producing a shared libraries from there without vcpkg being in the picture at all. The C++ people will know how to build their own libraries. The bigger question is then how to structure/create a nuget package via .nuspec so that the native libraries wind up in the target directory of the C# application that references the package. That expertise should exist within the nuget team, as it's just nuget functionality. Our approach was to use a .targets file, with the unfortunate side effect that the C# project that uses the native package sees all the shared libraries along side the source files in the solution explorer view. Yuck!

COMMENTS
from @Mizux
@jjpepper why do you use/hack a target file instead of setting it in the .*proj file ?
And did you try the property (which should work in .*proj) ?
src: https://docs.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-items?view=vs-2017#content

COMMENTS
from @tebeco
I'm really curious about a dotnet pack solution when vendor just gives you MyNative.dll and MyDotnetWapper.dll, refusing to create nupkg.

That's also a VERY common scenario for "legacy" nuget or third part that was used thx to <Reference and truing to move forward to <PackageReference by manually repackaging already built dll.
They are supposed to be repackaged to netstandard2.0 since some could target net47x for example.

As of today i never found a clear and clean solution :(

COMMENTS
from @tebeco
hello @karann-msft
would something like this helps as a support for documentation ?
#9502

This repository show a "way" that vendor uses (that is bad ... as they gives us RAW .net dll)
https://github.com/tebeco/NativeLibNugetStuff/blob/master/README.md

The original repo from @poke, shows a better way => properly packing the native + managed, it only depends on what you have on your hands
https://github.com/poke/NativeLibNugetStuff

I think both could be a good contribution to the the docs as it would helps vendor to have something to rely on, in order to release fully functional packages compliant with dotnet restore and dotnet publish

COMMENTS
from @Mizux
FYI I've updated https://github.com/Mizux/dotnet-native to add "real" C++ samples code up to the .Net wrapper generation (using SWIG to generate the .NET wrapper from the C++ code) and I've updated my documentation accordingly.

There is also github actions workflows CI and few Linux docker to test on various distros as well as tests using MacOS and Windows runners.

COMMENTS
from @tuket
What is the difference between "nativeassets" and "native" folders? What is the expected directory structure?

Verbose Logs

No response

[TeBeCo]

the post don't elaborate regarding the orignal comment that got posted
it barely mention this:

The \build folder can be used for all NuGet packages and not just native packages. The \build folder respects target frameworks just like the \content, \lib, and \tools folders. This means you can create a \build\net40 folder and a \build\net45 folder and NuGet will import the appropriate props and targets files into the project. (Use of PowerShell scripts to import MSBuild targets is not needed.)

which don't clarify:

• what each folders does and what it role is
• how to do that from dotnet pack and not manually crafting magic folder
• how to single pack both Native + their managed wrapper
• how the sub folder scaffolding works with dedicated RID
• how to target dedicated TFM in case or ns2.0 / net8.0