Clarification of lib vs ref & runtimes folders

[toptensoftware]

I'm hoping someone can clarify the correct usage of the /lib/ folder vs /ref/ and /runtimes/ folders.

I have a project that targets a couple of platforms, (eg: win and osx). The public api to is identical on all platforms, but the implementation on each is very different. eg: the windows build pinvokes to Win32, while the osx build uses ObjC interop.

From this documentation it sounds like the /lib/ folder should be used for platform independent assemblies and platform specific libraries the /ref/ folder should be used for compile time references and the /runtimes/ folder for the per-platform implementation assemblies. In other words you should use either:

• /lib/ OR
• /ref and /runtimes

So, I would expect this should work:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>

    <!-- snipped irrelevant stuff -->

    <references>
        <group targetFramework="net5.0">
            <reference file="packtest.dll" />
        </group>
    </references>

    <dependencies>
        <group targetFramework="net5.0">
        </group>
    </dependencies>

  </metadata>
  <files>
  
    <!-- net5.0 Reference -->
    <file src= ".\bin\Release\net5.0\packtest.dll" target="ref\net5.0" />

    <!-- net5.0 Runtime (Windows) -->
    <file src= ".\bin\Release\net5.0\packtest.dll" target="runtimes\win\lib\net5.0" />

    <!-- later, will be adding something like this-->
    <!-- net5.0 Runtime (OSX) -->
    <!--file src= ".\bin\Release\osx\net5.0\packtest.dll" target="runtimes\osx\lib\net5.0" /-->

  </files>
</package>

But, when building the package I get the following errors:

Error NU5018: Invalid assembly reference 'packtest.dll'. 
Ensure that a file named 'packtest.dll' exists in the lib directory.

Why? Shouldn't the files /ref and /runtimes suffice? What would the assembly in the root /lib/ folder be used for and wouldn't putting the assembly in the /lib/ folder result in the wrong assembly being used on unsupported target platforms?

Also:

• I've tried setting the reference group target framework to 'net5.0-windows7.0' but get the same error.
• I've tried changing the nuspec to also include both /lib/ folder and the /ref and /runtimes folders., but when I consume the package in a project I'm pretty sure it's using the lib folder and not the runtimes folder.
• I've tried guessing various flavors of the runtimes folder structure like : runtimes\win7-x64\lib\net5.0, runtimes\win10-x64\lib\net5.0 and runtimes\win7\lib\net5.0-windows7.0 but nuget seems insistent that something be provided in the /lib/ folder.

And finally, and perhaps most interestingly I tried this:

1. Built the package with all three /lib/, /ref/ and /runtimes/ folders
2. Opened the .nupkg as a zip file and deleted the /lib/ folder
3. Tested the package in a test project and it appears to work fine for compile, run and deploy.

Seems like nuget's error message is wrong and should allow empty /lib/ folder if there's /ref and /runtimes folders.

Am I missing something? Is there a work around for this? Any help greatly appreciated.

Using: nuget.exe version 5.10.0.7240

[zivkan]

Don't use the <references> section in the metadata. That's a packages.config-era feature, whereas the top level ref and runtimes folders are PackageReference only. In other words, <references> only works in lib/, which is where I expect the error is coming from. In PackageReference, assets under runtimes/ are never passed to the compiler, whereas assets under ref/ are only passed to the compiler, never copied to the output folder.

[toptensoftware]

Thanks for the fast reply. What you've described makes perfect sense but when I remove that section I get a warning to put it back:

WARNING: NU5131: References were found in the nuspec, but some reference assemblies were not found in both the nuspec and ref folder. Add the following reference assemblies:
- Add packtest.dll to the net5.0 reference group in the nuspec

The package seems to work fine though and at least the warning can be suppressed.

It's hard to get this stuff right when the warning is telling you to do the wrong thing. Or is it?

[zivkan]

NU5131 is encouraging you to make your package compatible for your package consumers who are using packages.config: https://docs.microsoft.com/en-us/nuget/create-packages/select-assemblies-referenced-by-projects

but by using the package's runtimes/ folder, it means the package can't be compatible with packages.config. Well, it could be, but you'd have to duplicate the work that NuGet does for the runtimes/ asset selection in your own targets file. So unfortunately as a package author of an advanced package, you need to decide whether you want to support your users who use packages.config, or if you'll only support users using PackageReference.

We should probably change NU5131 to only warn when a package is compatible with packages.config, but not PackageReference. SDK style projects don't support packages.config, and new versions of .NET can only be built with SDK style projects, hence fewer and fewer projects are going to use packages.config as time goes by. PackageReference compatibility is much more important for the future than packages.config compatibility.

For now, I suggest you <NoWarn>NU5131</NoWarn>

[toptensoftware]

Hi Andy. Thanks for your explanation of this. This is a private package that only needs to support SDK style projects so <nowarn> will suffice.

btw: the article you linked to mentions a /runtime folder. I presume that's a typo and they mean /runtimes?