diff --git a/docs/coding-guidelines/libraries-packaging.md b/docs/coding-guidelines/libraries-packaging.md new file mode 100644 index 00000000000000..caf447ca598a10 --- /dev/null +++ b/docs/coding-guidelines/libraries-packaging.md @@ -0,0 +1,101 @@ +# Packaging + +Libraries can be packaged in one or more of the following ways: as part of the .NETCore shared framework, part of a transport package, or as a NuGet package. + +## .NETCore Shared framework + +To add a library to the .NETCore shared framework, that library's `AssemblyName` should be added to [NetCoreAppLibrary.props](../../src/libraries/NetCoreAppLibrary.props) + +The library should have both a `ref` and `src` project. Its reference assembly will be included in the ref-pack for the Microsoft.NETCore.App shared framework, and its implementation assembly will be included in the runtime pack. + +Including a library in the shared framework only includes the best applicable TargetFramework build of that library: `$(NetCoreAppCurrent)` if it exists, but possibly `netstandard2.1` or another if that is best. If a library has builds for other frameworks those will only be shipped if the library also produces a [Nuget package](#nuget-package). If a library ships both in the shared framework and a nuget package, it may decide to exclude its latest `$(NetCoreAppCurrent)` build from the package. This can be done by setting `ExcludeCurrentNetCoreAppFromPackage` to true. Libraries should take care when doing this to ensure that whatever asset in the package that would apply to `$(NetCoreAppCurrent)` is functionally equivalent to that which it replaces from the shared framework, to avoid breaking applications which reference a newer package than the shared framework. If possible, it's preferable to avoid this by choosing to target frameworks which can both ship in the package and shared framework. + +In some occasions we may want to include a library in the shared framework, but not expose it publicly. To do so, include the library in the `NetCoreAppLibraryNoReference` property in [NetCoreAppLibrary.props](../../src/libraries/NetCoreAppLibrary.props). The library should also be named in a way to discourage use at runtime, for example using the `System.Private` prefix. We should avoid hiding arbitrary public libraries as it complicates deployment and servicing, though some platform specific libraries are in this state due to historical reasons. + +Libraries included in the shared framework should ensure all direct and transitive assembly references are also included in the shared framework. This will be validated as part of the build and errors raised if any dependencies are unsatisfied. + +Removing a library from the shared framework is a breaking change and should be avoided. + +## Transport package + +Transport packages are non-shipping packages that dotnet/runtime produces in order to share binaries with other repositories. + +### Microsoft.AspNetCore.Internal.Transport + +This package represents the set of libraries which are produced in dotnet/runtime and ship in the ASP.NETCore shared framework. We produce a transport package so that we can easily share reference assemblies and implementation configurations that might not be present in NuGet packages that also ship. + +To add a library to the ASP.NETCore shared framework, that library should set the `IsAspNetCoreApp` property for its `ref` and `src` project. This is typically done in the library's `Directory.Build.props`, for example https://github.com/dotnet/runtime/blob/98ac23212e6017c615e7e855e676fc43c8e44cb8/src/libraries/Microsoft.Extensions.Logging.Abstractions/Directory.Build.props#L4. + +Libraries included in this transport package should ensure all direct and transitive assembly references are also included in either the ASP.NETCore shared framework or the .NETCore shared framework. This is not validated in dotnet/runtime at the moment: https://github.com/dotnet/runtime/issues/52562 + +Removing a library from this transport package is a breaking change and should be avoided. + +## NuGet package + +Libraries to be packaged must be referenced by the [traversal packaging project](../../src/libraries/libraries-packages.proj) and set `IsPackable` to true. By default, all `Libraries/*/src` projects are considered for packaging. + +Package versions and shipping state should be controlled using the properties defined by the [Arcade SDK](https://github.com/dotnet/arcade/blob/master/Documentation/ArcadeSdk.md#project-properties-defined-by-the-sdk). Typically libraries should not need to explicitly set any of these properties. + +Most metadata for packages is controlled centrally in the repository and individual projects may not need to make any changes to these. One property is required to be set in each project: `PackageDescription`. This should be set to a descriptive summary of the purpose of the package, and a list of common entry-point types for the package: to aide in search engine optimization. Example: +```xml +Logging abstractions for Microsoft.Extensions.Logging. + +Commonly Used Types: +Microsoft.Extensions.Logging.ILogger +Microsoft.Extensions.Logging.ILoggerFactory +Microsoft.Extensions.Logging.ILogger<TCategoryName> +Microsoft.Extensions.Logging.LogLevel +Microsoft.Extensions.Logging.Logger<T> +Microsoft.Extensions.Logging.LoggerMessage +Microsoft.Extensions.Logging.Abstractions.NullLogger +``` + +Package content can be defined using any of the publicly defined Pack inputs: https://docs.microsoft.com/en-us/nuget/reference/msbuild-targets + +### TargetFrameworks + +By default all TargetFrameworks listed in your project will be included in the package. You may exclude specific TargetFrameworks by setting `ExcludeFromPackage` on that framework. +```xml + + true + +``` + +A common pattern is to build for the latest .NET version, for example to include a library in the shared framework or a transport package, but then excluded this from the NuGet package. This can be done to avoid growing the NuGet package in size. To do this set +```xml + + true + +``` + +When excluding TargetFrameworks from a package special care should be taken to ensure that the builds included are equivalent to those excluded. Avoid ifdef'ing the implementation only in an excluded TargetFramework. Doing so will result in testing something different than what we ship, or shipping a nuget package that degrades the shared framework. + +### Build props / targets and other content + +Build props and targets may be needed in NuGet packages. To define these, author a build folder in your src project and place the necessary props/targets in this subfolder. You can then add items to include these in the package by defining `Content` items and setting `PackagePath` as follows: +```xml + + + + +``` + +### Analyzers / source generators + +Some packages may wish to include a companion analyzer or source-generator with their library. Analyzers are much different from normal library contributors: their dependencies shouldn't be treated as nuget package dependencies, their TargetFramework isn't applicable to the project they are consumed in (since they run in the compiler). To facilitate this, we've defined some common infrastructure for packaging Analyzers. + +To include an analyzer in a package, simply add an `AnalyzerReference` item to the project that produces the package that should contain the analyzer +```xml + + + +``` + +In the analyzer project make sure to do the following. Ensure it only targets `netstandard2.0` since this is a requirement of the compiler. Enable localization by setting `UsingToolXliff`. Set the `AnalyzerLanguage` property to either `cs` or `vb` if the analyzer is specific to that language. By default the analyzer will be packaged as language-agnostic. Avoid any dependencies in Analyzer projects that aren't already provided by the compiler. +```xml + + netstandard2.0 + true + cs + +``` diff --git a/docs/coding-guidelines/package-projects.md b/docs/coding-guidelines/package-projects.md index 375ec4b1e72991..3e3caa257344b4 100644 --- a/docs/coding-guidelines/package-projects.md +++ b/docs/coding-guidelines/package-projects.md @@ -1,4 +1,6 @@ # Package projects +** IMPORTANT ** Package projects are in the process of being deprecated, please do not create new package projects. Instead use normal projects (csproj) following the guidelines here: [libraries-packaging](libraries-packaging.md) + Package projects bring together all the assemblies that make up a library on different platforms into a set of NuGet packages. ## Package hierarchy diff --git a/eng/Tools.props b/eng/Tools.props index a9a9fb714be97c..04f1c9d742510c 100644 --- a/eng/Tools.props +++ b/eng/Tools.props @@ -7,7 +7,7 @@ - + diff --git a/eng/Version.Details.xml b/eng/Version.Details.xml index 6987581bbaa4d6..8c66a98eff1d7f 100644 --- a/eng/Version.Details.xml +++ b/eng/Version.Details.xml @@ -186,9 +186,9 @@ https://github.com/dotnet/xharness 9596c3fbbb718819bc4bb9a9e3f6271b50fc718a - + https://github.com/dotnet/arcade - 44324e2d3563921f60b1522fccf3fef45dcfe636 + 6b9758661f4483a70654bcaf6f8d7c6a79ee5660 https://dev.azure.com/dnceng/internal/_git/dotnet-optimization diff --git a/eng/Versions.props b/eng/Versions.props index ca2b8559c1249f..b841abb2fa4ea0 100644 --- a/eng/Versions.props +++ b/eng/Versions.props @@ -63,7 +63,7 @@ 6.0.0-beta.21263.1 6.0.0-beta.21263.1 6.0.0-beta.21263.1 - 6.0.0-beta.21260.1 + 6.0.0-beta.21263.1 5.9.0-preview.2 diff --git a/src/libraries/Directory.Build.targets b/src/libraries/Directory.Build.targets index 70faee0244f557..bf72681fcd78ea 100644 --- a/src/libraries/Directory.Build.targets +++ b/src/libraries/Directory.Build.targets @@ -301,4 +301,50 @@ + + IncludeAnalyzersInPackage;$(BeforePack) + + + + + + + + + + + + + + + + + <_TargetPathsToSymbols Include="@(_AnalyzerFile)" TargetPath="/%(_AnalyzerFile.PackagePath)" Condition="%(_AnalyzerFile.IsSymbol)" /> + + + + + + <_analyzerPath>analyzers/dotnet + <_analyzerPath Condition="'$(AnalyzerLanguage)' != ''">$(_analyzerPath)/$(AnalyzerLanguage) + + + <_AnalyzerPackFile Include="@(_BuildOutputInPackage)" IsSymbol="false" /> + <_AnalyzerPackFile Include="@(_TargetPathsToSymbols)" IsSymbol="true" /> + <_AnalyzerPackFile PackagePath="$(_analyzerPath)/%(TargetPath)" /> + + + + diff --git a/src/libraries/Microsoft.Extensions.Logging.Abstractions/gen/Microsoft.Extensions.Logging.Generators.csproj b/src/libraries/Microsoft.Extensions.Logging.Abstractions/gen/Microsoft.Extensions.Logging.Generators.csproj index 719c9011b391e5..1531036a02e811 100644 --- a/src/libraries/Microsoft.Extensions.Logging.Abstractions/gen/Microsoft.Extensions.Logging.Generators.csproj +++ b/src/libraries/Microsoft.Extensions.Logging.Abstractions/gen/Microsoft.Extensions.Logging.Generators.csproj @@ -7,18 +7,10 @@ false true false + false + cs - - - - - - - - - - diff --git a/src/libraries/Microsoft.Extensions.Logging.Abstractions/pkg/Microsoft.Extensions.Logging.Abstractions.pkgproj b/src/libraries/Microsoft.Extensions.Logging.Abstractions/pkg/Microsoft.Extensions.Logging.Abstractions.pkgproj deleted file mode 100644 index 6b854423d7afe9..00000000000000 --- a/src/libraries/Microsoft.Extensions.Logging.Abstractions/pkg/Microsoft.Extensions.Logging.Abstractions.pkgproj +++ /dev/null @@ -1,10 +0,0 @@ - - - - - net461;netcoreapp2.0;uap10.0.16299;$(AllXamarinFrameworks) - - - - - \ No newline at end of file diff --git a/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/Microsoft.Extensions.Logging.Abstractions.csproj b/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/Microsoft.Extensions.Logging.Abstractions.csproj index 10623a70179042..d63b42d63f3a67 100644 --- a/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/Microsoft.Extensions.Logging.Abstractions.csproj +++ b/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/Microsoft.Extensions.Logging.Abstractions.csproj @@ -8,7 +8,16 @@ false enable - false + Logging abstractions for Microsoft.Extensions.Logging. + +Commonly Used Types: +Microsoft.Extensions.Logging.ILogger +Microsoft.Extensions.Logging.ILoggerFactory +Microsoft.Extensions.Logging.ILogger<TCategoryName> +Microsoft.Extensions.Logging.LogLevel +Microsoft.Extensions.Logging.Logger<T> +Microsoft.Extensions.Logging.LoggerMessage +Microsoft.Extensions.Logging.Abstractions.NullLogger @@ -27,4 +36,8 @@ + + + + diff --git a/src/libraries/System.Text.Json/src/System.Text.Json.csproj b/src/libraries/System.Text.Json/src/System.Text.Json.csproj index fdfaf63b9c1ff5..1d5c0eb83d53c7 100644 --- a/src/libraries/System.Text.Json/src/System.Text.Json.csproj +++ b/src/libraries/System.Text.Json/src/System.Text.Json.csproj @@ -309,6 +309,9 @@ + + + diff --git a/src/libraries/pkg/test/testPackages.proj b/src/libraries/pkg/test/testPackages.proj index c8ce490bca615d..2dcacddce6c578 100644 --- a/src/libraries/pkg/test/testPackages.proj +++ b/src/libraries/pkg/test/testPackages.proj @@ -82,7 +82,7 @@ - + diff --git a/src/libraries/src.proj b/src/libraries/src.proj index 524316618c2fb0..dae9e457a0f544 100644 --- a/src/libraries/src.proj +++ b/src/libraries/src.proj @@ -7,12 +7,8 @@ <_allSrc Include="$(MSBuildThisFileDirectory)*\src\*.csproj" Exclude="@(ProjectExclusions)" /> - -