csproj: document how to properly pack platform-specific native assemblies

[yatli]

Details about Problem

NuGet product used (NuGet.exe | VS UI | Package Manager Console | dotnet.exe): dotnet.exe

dotnet.exe --version (if appropriate): 2.1.4

OS version (i.e. win10 v1607 (14393.321)): win10 v1709 (16299.248)

Description

We've got rid and tfm specific native assemblies in a package but until very recently I haven't find enough documentation about how to pack them and let the runtime pick the appropriate native library automatically.

Relevant links:

• New csproj additions -- I find the IncludeAssets value "Native" which says "native assemblies" will be copied over. So where are they?
• Nuget MSBuild targets -- traditional folders like build/, tools/, lib/, etc.
• Fragmented information about project.json, mentioning runtimes/win-x64 and so on -- , but how am I supposed to know that this convention is carried over to the new csproj?

I have to look into the Nuget code repo, and here: https://github.com/NuGet/NuGet.Client/blob/023fe7670796a8986bbfdc520029e4cf0a6bbfda/src/NuGet.Core/NuGet.Packaging/ContentModel/ManagedCodeConventions.cs#L452

That's it, now I know it's runtimes/{rid}/native/{any?}. Searching for a concrete example on the internet:
I get issues, not documentation.
Searching for "nuget pack native assemblies" did not work either..
It turns out, the correct information is located here: - Bingo!
However, this page is advertised as "Supporting multiple .NET framework versions", which is really orthogonal to what I want. Multi-targeting is about tfm, and platform-specific stuff are about rid -- I have never found a single page that connects all these dots together.

So I suggest documenting such behavior at the following docs sites:

1. "Additions to the csproj format" -- https://docs.microsoft.com/en-us/dotnet/core/tools/csproj
2. "Package creation workflow" -- https://docs.microsoft.com/en-us/nuget/create-packages/overview-and-workflow -- there's multi-targeting page, and a native packages page, and I think it's better to create a new page "platform-specific native libraries" to avoid confusion.
3. Also, document that runtimes/{rid}/native does not work with netfx -- you have to place native dlls in the lib/ folder (risky, could cause msbuild warnings/errors), or embed the dlls and release them at runtime.

[veikkoeeva]

Also relevant is #3931 and #4837 (comment).

[PatoBeltran]

@karann-msft can you please take a look at this issue?

[PatoBeltran]

@nkolev92 maybe you can provide more context on how this can be solved

[veikkoeeva]

@PatoBeltran To me the greatest problem was the information that is scattered. I also came quickly around the documentation @yatli refers to, but it didn't spark the lightbulb immediately. Partially because I didn't first understand there's a difference with the new reference method and how it's done before that and that one really needs a .target file. It might be useful to point out these distinctions explicitly (and that there's old documentation). Maybe also give instructions to look at obj folder and how do all the elements fit into the whole system. This includes such things as the managed libraries can be found in the global Nuget index and don't need to be copied over, but calling native files, or putting content files/executables/P/Invoke assets (it's maybe important to enumerate hese explicitly for the sake to reduce cognitive stress) one needs to pick them up with a .target file. For reference, #3931 (comment) is the SO issue I opened and linked various things.

[yatli]

@PatoBeltran just like @veikkoeeva mentioned, the information is too fragmented and it is very hard to pull the pieces together. You see, even though I have looked directly at the source code and completely understand how to proceed, I tried to reverse engineer a valid search query for the answer that I already know, and I failed.

[ektrah]

3. Also, document that runtimes/{rid}/native does not work with netfx -- you have to place native dlls in the lib/ folder (risky, could cause msbuild warnings/errors), or embed the dlls and release them at runtime.

runtimes/{rid}/native does work with .NET Framework — under very narrow, undocumented conditions. It's a mystery.

Any kind of official information on this would be highly welcome.

[veikkoeeva]

Cross-referencing #5910. Basically the same issue.

[karann-msft]

cc: @anangaur @kraigb

[Apollo3zehn]

After some testing, it seems that for corefx the RID fallback mechanism works as expected (e.g. win7-x86 -> win-x86 -> win -> any). But for netfx you need to specify the exact same RID in the .csproj that appears in the nuget package under runtimes/{rid}/native. Otherwise the native .dll's are not copied to the output directory. The same happens if no <RuntimeIdentifier>...<RuntimeIdentifier> is specificed at all.

Instead, without RID specified, corefx copies the whole runtimes/* folder and the application finds the correct libraries during runtime. I would expect the same behavior for netfx. But I think this is not possible because there is no deps.json which would point to the available files.

[deinok]

Hi, I'm trying to include MRAA to a NetStandard project.

<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk">

	<PropertyGroup>
		<TargetFrameworks>netstandard1.1;netstandard2.0</TargetFrameworks>
	</PropertyGroup>

	<ItemGroup>
		<Content CopyToOutputDirectory="PreserveNewest" Include="runtimes/linux-arm/native/libmraa.so" Link="libmraa.so" Pack="true" PackagePath="runtimes/linux-arm/native/libmraa.so" />
		<Content CopyToOutputDirectory="PreserveNewest" Include="runtimes/linux-arm/native/libmraa.so.2" Link="libmraa.so.2" Pack="true" PackagePath="runtimes/linux-arm/native/libmraa.so.2" />
		<Content CopyToOutputDirectory="PreserveNewest" Include="runtimes/linux-arm/native/libmraa.so.2.0.0" Link="libmraa.so.2.0.0" Pack="true" PackagePath="runtimes/linux-arm/native/libmraa.so.2.0.0"/>
		<Content CopyToOutputDirectory="PreserveNewest" Include="runtimes/linux-x64/native/libmraa.so" Link="libmraa.so" Pack="true" PackagePath="runtimes/linux-x64/native/libmraa.so" />
		<Content CopyToOutputDirectory="PreserveNewest" Include="runtimes/linux-x64/native/libmraa.so.2" Link="libmraa.so.2" Pack="true" PackagePath="runtimes/linux-x64/native/libmraa.so.2" />
		<Content CopyToOutputDirectory="PreserveNewest" Include="runtimes/linux-x64/native/libmraa.so.2.0.0" Link="libmraa.so.2.0.0" Pack="true" PackagePath="runtimes/linux-x64/native/libmraa.so.2.0.0"/>
	</ItemGroup>

</Project>

And I'm using this: [DllImport("libmraa")]

If libmraa is installed, all the code works well, but i want to create a Package that include the precompiled mraa and the SO doesn't have libmraa installed it says: File not found.
Did I left something?