Recommendations for new structure of NuGet packages for .NET projects

I have already written about disadvantages of existing packages and gave several recommendations for improving it (see the [“Recommendations for improving an existing NuGet packages for .NET projects”](https://github.com/chakra-core/ChakraCore/issues/6572) issue). In this post, I will write about more radical changes - new structure of NuGet packages. Currently, .NET developers using the ChakraCore library have only one official package available - [Microsoft.ChakraCore](https://www.nuget.org/packages/Microsoft.ChakraCore), which has two significant disadvantages:

1. This package is focused exclusively on Windows and contains assemblies for the following processor architectures: x86, x64 and ARM. Ability to build a library for the ARM64 architecture has existed for at least six months, but nevertheless the corresponding assembly is not included in either [official releases](https://github.com/chakra-core/ChakraCore/releases) or NuGet package.
1. Now this package weighs about 7 MB. If we add assemblies for three most popular platforms (Windows (ARM64), Linux (x64) and OS X (x64)) to it, then it will already weigh more than 40 MB, which may cause problems for some users.

These problems can be solved by creating separate packages for each platform and converting the Microsoft.ChakraCore package to a metapackage. Some developers, including me, have done so by publishing their own packages: JavaScriptEngineSwitcher.ChakraCore.Native.\*, BaristaLabs.BaristaCore.ChakraCore.\* and ReactWindows.ChakraCore.ARM64. Appearance of official packages, created according to similar principles, would led to three positive points:

1. Removing additional burden from developers of unofficial packages.
1. Increasing trust of end users to packages.
1. Increasing number of downloads of official packages.

I will list the main steps that you need to do to create such packages (examples still use the old package naming system):

1. **Move a source code of each NuGet package to separate directory.** At the moment, all `.nuspec` and `.props` files are located in the same directory. It would be more optimal to [create a separate directory for each package and move these files there](https://github.com/Taritsyn/ChakraCore/commit/f6f99568514bedf65ce287055f9e763a9141186b). In the future, this would make it easier to add new files to packages (for example, PowerShell scripts).
1. **Use a RID's in NuGet package names**. There are already three platform-specific packages, but they just haven't been published. Since we are also planning to create packages for operating systems other than Windows, then we should use a [runtime identifiers](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog) in its names. I suggest [renaming the platform-specific packages](https://github.com/Taritsyn/ChakraCore/commit/64ed4c6d541d43d62ef2a4ae92f9d1373c938290) as follows:
* Microsoft.ChakraCore.X86 -> Microsoft.ChakraCore.win-x86
* Microsoft.ChakraCore.X64 -> Microsoft.ChakraCore.win-x64
* Microsoft.ChakraCore.ARM -> Microsoft.ChakraCore.win-arm
1. **Implement in MSBuild scripts of platform-specific packages a same deployment mechanism as in the Microsoft.ChakraCore package.** Currently, platform-specific packages cannot be used together, because their assemblies overwrite each other. To prevent this, in the `.props` files you need to [use a code similar to code from the `Microsoft.ChakraCore.props` file](https://github.com/Taritsyn/ChakraCore/commit/4b7cfe38851a7d7778829b83ec26a4fbe5b5bf09).
1. **Add a platform-specific “symbol” packages.** Having looked at the [NuGet.org](https://www.nuget.org/) site many packages that contain native assemblies, I did not find a no one package for which symbols were loaded. It seems that for packages with native assemblies, can't create symbol packages in either old (`.symbols.nupkg`) or new (`.snupkg`) format. Therefore, to create a platform-specific “symbol” packages, we will use the same approach as in the `Microsoft.ChakraCore.Symbols` package: [create a regular NuGet packages that will deploy the `.pdb` files instead of the `.dll` files](https://github.com/Taritsyn/ChakraCore/commit/906992e451adecf3c7a509459a3fbfab7dd6758c).
1. **Convert a Microsoft.ChakraCore and Microsoft.ChakraCore.symbols packages to metapackages.** Since we now have primary and “symbol” platform-specific packages, then we can convert the Microsoft.ChakraCore and Microsoft.ChakraCore.symbols packages to metapackages. To do this, we will simply [remove the logic from these packages and add references to platform-specific packages as dependencies](https://github.com/Taritsyn/ChakraCore/commit/f9d3d3abfbced64658b47b2bb5830c23bb3a4495). We keep these packages only for backward compatibility and they will always be intended for Windows.
1. **Add to platform-specific packages a PowerShell scripts that are responsible for deploying assemblies and `.pdb` files on ASP.NET 4.X websites.** Unfortunately, MSBuild scripts are not suitable for all use cases of .NET Framework. For example, ASP.NET 4.X web sites don't have project files and need to use a PowerShell scripts to deploy the native assemblies in the `bin` directory. To make it possible to use packages on ASP.NET 4.X web sites, we will [add the `Install.ps1` and `Uninstall.ps1` scripts to platform-specific packages](https://github.com/Taritsyn/ChakraCore/commit/176c1d991460951d4de3c27eaff5edab9c015a25).
1. **Add a support for Windows (ARM64) platform.** To create primary and “symbol” packages oriented on the ARM64 processor architecture, you can [take the Microsoft.ChakraCore.win-arm.* packages as a basis and just add the `64` numbers in right places](https://github.com/Taritsyn/ChakraCore/commit/9b72d1d109aed560c3ba411dc5cb1eafec450a50). In sample code, I also added the created packages to metapackages as dependencies, as this seemed reasonable to me.
1. **Add a Windows batch file that runs the PowerShell script to create NuGet packages (optional).** Since running the `package.ps1` script by using Windows PowerShell requires certain skills, then [I renamed it to the `pack.ps1` and created a batch file (`pack.cmd`)](https://github.com/Taritsyn/ChakraCore/commit/ef008e2a83d05491edf6ecfe31f6449fffddcaac) to simplify this procedure.
1. **Add a NuGet packages for Linux (x64) and OS X (x64).** [Packages containing assemblies for 64-bit Linux and OS X are extremely simple](https://github.com/Taritsyn/ChakraCore/commit/dcade76e9f585057fb34a79aae3c8027ac002220), because they are intended only for .NET Core. Because .NET Framework is not supported on Linux and OS X, then to run the `nuget.exe` need to install the [Mono](https://www.mono-project.com/). A simple Bash script (`pack.sh`) is used to run the packaging process. Ability to create a “symbol” packages is not yet available.

There is also an alternative way to run the packaging process, when [using only one script (`pack.ps1`)](https://github.com/Taritsyn/ChakraCore/commit/9217c71d023da170feddc86139cd1a45f35b765c) written for the [cross-platform PowerShell](https://github.com/PowerShell/PowerShell). Running a script by using this version of PowerShell looks much easier:

```
pwsh pack.ps1
```

Everything described in this post is already available as a ready-made solution for creating a NuGet packages. Moreover, it is available in two variants: [standard](https://github.com/Taritsyn/ChakraCore/tree/nuget-package-reorganization-demo/Build/NuGet) and [one-script](https://github.com/Taritsyn/ChakraCore/tree/nuget-package-reorganization-pwsh-only-demo/Build/NuGet). I am ready to implement each of these recommendations in the form of pull request.

**P.S.:** I did not touch the `Microsoft.ChakraCore.SignNuget.proj` and `packages.config` files, because I do not know exactly how they are used. Most likely, they are used to install the [MicroBuild.Core](https://www.nuget.org/packages/MicroBuild.Core/) and [SrcSrv](https://www.nuget.org/packages/SrcSrv/) packages, but it is better to check with Microsoft employees.