Major per-RuntimeIdentifier build refactoring

novotnyllc · Apr 3, 2020 · d930de9 · d930de9
1 parent 42d2fff
commit d930de9
Show file tree

Hide file tree

Showing 18 changed files with 680 additions and 108 deletions.
diff --git a/MSBuild.Sdk.Extras.sln b/MSBuild.Sdk.Extras.sln
@@ -36,7 +36,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tools", "Tools", "{19A683CB
 		Tools\MSBuild.Packaging.targets = Tools\MSBuild.Packaging.targets
 	EndProjectSection
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "UwpClassLibrary", "Tests\UwpClassLibrary\UwpClassLibrary.csproj", "{B7617E50-4107-4C19-BDCF-012CCDB22FB0}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "UwpClassLibrary", "Tests\UwpClassLibrary\UwpClassLibrary.csproj", "{B7617E50-4107-4C19-BDCF-012CCDB22FB0}"
+EndProject
+Project("{13B669BE-BB05-4DDF-9536-439F39A36129}") = "ClasslibPackTests", "Tests\ClasslibPackTests.msbuildproj", "{8DB76FFF-B050-433B-B478-1FC44DB9DF6B}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -80,6 +82,10 @@ Global
 		{B7617E50-4107-4C19-BDCF-012CCDB22FB0}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B7617E50-4107-4C19-BDCF-012CCDB22FB0}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{B7617E50-4107-4C19-BDCF-012CCDB22FB0}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8DB76FFF-B050-433B-B478-1FC44DB9DF6B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8DB76FFF-B050-433B-B478-1FC44DB9DF6B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8DB76FFF-B050-433B-B478-1FC44DB9DF6B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8DB76FFF-B050-433B-B478-1FC44DB9DF6B}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -94,6 +100,7 @@ Global
 		{C2EE161F-0521-47F7-BE2D-0B55CA8B3C53} = {26026DB4-DD68-43BF-8858-15AD2016C0B2}
 		{19A683CB-8C5D-480B-8D60-30F28DA40660} = {8647C74A-083C-4EAF-B9B0-2172D4A27BFC}
 		{B7617E50-4107-4C19-BDCF-012CCDB22FB0} = {26026DB4-DD68-43BF-8858-15AD2016C0B2}
+		{8DB76FFF-B050-433B-B478-1FC44DB9DF6B} = {26026DB4-DD68-43BF-8858-15AD2016C0B2}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {93349570-79D8-4F89-8E78-C66401620727}

diff --git a/README.md b/README.md
@@ -97,23 +97,45 @@ More information on how SDK's are resolved can be found [here](https://docs.micr
 
 ### <a id="rids"></a>Creating Per-RuntimeIdentifier packages
 
-You'll need a few things
+You'll need to perform a few simple steps:
 
-1. Make sure to use `TargetFrameworks` instead of `TargetFramework`, even if you're only building a single target framework. I am piggy-backing off of its looping capabilities.
-2. Set the `RuntimeIdentifiers` property to [valid RID's](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog) ([full list](https://github.com/dotnet/runtime/blob/master/src/libraries/pkg/Microsoft.NETCore.Platforms/runtime.json)), separated by a semi-colon. (`<RuntimeIdentifiers>win;unix</RuntimeIdentifiers>`). These can be set per TFM using a condition on the property. This lets you have multiple TFM's, but only some of which have RID's.
-3. For the TFM's that you want want to build separately, set the  property `ExtrasBuildEachRuntimeIdentifier` to `true`.
+1. Set the `RuntimeIdentifiers` property to [valid RID's](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog) ([full list](https://github.com/dotnet/runtime/blob/master/src/libraries/pkg/Microsoft.NETCore.Platforms/runtime.json)), separated by a semi-colon (`<RuntimeIdentifiers>win;unix</RuntimeIdentifiers>`).
+2. For the TFM's that you want want to build separately, set the `ExtrasBuildEachRuntimeIdentifier` property to `true`.
 
-Note: You must use the `Sdk="MSBuild.Sdk.Extras"` method for this. Using `PackageReference` is unsupported for this scenario.
+When you're done, you should be able to run build/pack and it'll produce a NuGet package.
 
-While the Visual Studio context won't show each RID, it'll build for each. The Extras defines a symbol for each RID for use (`win-x86` would be `WIN_X86` and `centos.7-x64` would be `CENTOS_7_X64`). Dots and dashes become underbars.
+Notes:
+* You must use the `Sdk="MSBuild.Sdk.Extras"` method for this. Using `PackageReference` is unsupported for this scenario.
+* While the Visual Studio context won't show each RID, it'll build for each.
+* The Extras defines a preprocessor symbol for each RID for use (`win-x86` would be `WIN_X86` and `centos.7-x64` would be `CENTOS_7_X64`). Dots and dashes become underbars.
+* The default path for per-RID output assemblies and symbols in NuGet package is `runtimes/<RuntimeIdentifier>/lib/<TargetFramework>`.
+* `RuntimeIdentifiers` can be set per-`TargetFramework` using a condition on the property. This lets you have multiple TFM's, but only some of which have RID's.
 
-You will also need a Reference Assembly for the `ref` folder. Please see my [two](https://claires.site/2018/07/09/create-and-pack-reference-assemblies-made-easy/) [blogs](https://claires.site/2018/07/03/create-and-pack-reference-assemblies/) articles for details.
-
-When you're done, you should be able to build/pack these and it'll create a NuGet package. Your per-RID targets will be in `runtimes/<rid>/lib/<tfm>` and the Reference Assembly will be in `ref/<tfm>`.
+#### Reference Assemblies
+You will likely need to create reference assemblies to simplify development and consumption of your libraries with complex flavor (`TargetFramework` × `RuntimeIdentifier`) matrix.
+Reference assemblies are packed into `ref/<TargetFramework>` folder. Please see my [two](https://claires.site/2018/07/09/create-and-pack-reference-assemblies-made-easy/) [blogs](https://claires.site/2018/07/03/create-and-pack-reference-assemblies/) articles for details.
 
+#### Packing additional contents
 If you need to add native assets into runtimes, the easiest way is to use:
+```xml
+<None Include="path/to/native.dll" PackagePath="runtimes/<rid>/native" Pack="true" />
+```
+
+#### Overriding content paths in output package
+Minimal example to pack output assemblies and symbols to `tools` (instead of `runtimes`) subfolders.
+```xml
+<PropertyGroup>
+  <ExtrasIncludeDefaultProjectBuildOutputInPackTarget>IncludeDefaultProjectBuildOutputInPack</ExtrasIncludeDefaultProjectBuildOutputInPackTarget>
+</PropertyGroup>
+
+<Target Name="IncludeDefaultProjectBuildOutputInPack">
+  <ItemGroup>
+    <None Include="@(RidSpecificOutput)" PackagePath="tools/%(TargetFramework)/%(Rid)" Pack="true" />
+  </ItemGroup>
+</Target>
+```
 
-`<None Include="path/to/native.dll" PackagePath="runtimes/<rid>/native" Pack="true" />`
+For advanced options, see _ClasslibPack*_ SDK tests and _RIDs.targets_ file.
 
 
 ### Migrate from the old way (VS pre-15.6)