From e5b7093b4d1103f147b9a1a5ea56ee6409076353 Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Tue, 4 May 2021 17:53:46 -0700 Subject: [PATCH 1/8] Add Analyzer packaging support and packaging documentation To package Microsoft.Extensions.Logging.Abstractions we needed support for packing an Analyzer. This adds that support. I wanted to document this addition, so I created the start of a doc that's meant to describe the packaging options for libraries in dotnet/runtime. --- docs/coding-guidelines/libraries-packaging.md | 101 ++++++++++++++++++ docs/coding-guidelines/package-projects.md | 2 + src/libraries/Directory.Build.targets | 45 ++++++++ ...osoft.Extensions.Logging.Generators.csproj | 12 +-- ...ft.Extensions.Logging.Abstractions.pkgproj | 10 -- ...oft.Extensions.Logging.Abstractions.csproj | 15 ++- 6 files changed, 164 insertions(+), 21 deletions(-) create mode 100644 docs/coding-guidelines/libraries-packaging.md delete mode 100644 src/libraries/Microsoft.Extensions.Logging.Abstractions/pkg/Microsoft.Extensions.Logging.Abstractions.pkgproj diff --git a/docs/coding-guidelines/libraries-packaging.md b/docs/coding-guidelines/libraries-packaging.md new file mode 100644 index 00000000000000..8839369f86c587 --- /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. It's reference assembly will be included in the ref-pack for the Microsoft.NETCore.App shared framework, and it's implementation assembly will be included in the runtime pack. + +Including a library in the shared framework only includes the latest framework builds of that library (`$(NetCoreAppCurrent)`). 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 frameork and a nuget package, it may decide to exclude it's 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 a library should be excluded from the ref-pack and not visible to customers targeting that shared framework, the library may be included in the `NetCoreAppLibraryNoReference` property in [NetCoreAppLibrary.props](../../src/libraries/NetCoreAppLibrary.props). + +Libraries included in the shared framework should ensure their closure is 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 it's `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 be closure complete with respect to both ASP.NETCore shared framework and the .NETCore shared framework. TODO: validate this when building the transport package. + +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 need not 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 sepecific 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 add 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..a96f57709303c3 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 nopt 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/src/libraries/Directory.Build.targets b/src/libraries/Directory.Build.targets index 33fe06f303da7d..42c6c133998097 100644 --- a/src/libraries/Directory.Build.targets +++ b/src/libraries/Directory.Build.targets @@ -299,4 +299,49 @@ + + IncludeAnalyzersInPackage;$(BeforePack) + + + + + + + + + + + + + + + + + <_TargetPathsToSymbols Include="@(_AnalyzerFiles)" TargetPath="/%(_AnalyzerFiles.PackagePath)" Condition="%(_AnalyzerFiles.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 @@ + + + + From 5ce1b6f9ce85bf9e7fc014c3e009011b0feafb0b Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Mon, 10 May 2021 13:25:57 -0700 Subject: [PATCH 2/8] Address code review feedback. --- docs/coding-guidelines/libraries-packaging.md | 10 +++++----- docs/coding-guidelines/package-projects.md | 2 +- src/libraries/Directory.Build.targets | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/coding-guidelines/libraries-packaging.md b/docs/coding-guidelines/libraries-packaging.md index 8839369f86c587..c560aac7c94d61 100644 --- a/docs/coding-guidelines/libraries-packaging.md +++ b/docs/coding-guidelines/libraries-packaging.md @@ -8,11 +8,11 @@ To add a library to the .NETCore shared framework, that library's `AssemblyName The library should have both a `ref` and `src` project. It's reference assembly will be included in the ref-pack for the Microsoft.NETCore.App shared framework, and it's implementation assembly will be included in the runtime pack. -Including a library in the shared framework only includes the latest framework builds of that library (`$(NetCoreAppCurrent)`). 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 frameork and a nuget package, it may decide to exclude it's 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. +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 it's 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 prefferable to avoid this by choosing to target frameworks which can both ship in the package and shared framework. If a library should be excluded from the ref-pack and not visible to customers targeting that shared framework, the library may be included in the `NetCoreAppLibraryNoReference` property in [NetCoreAppLibrary.props](../../src/libraries/NetCoreAppLibrary.props). -Libraries included in the shared framework should ensure their closure is also included in the shared framework. This will be validated as part of the build and errors raised if any dependencies are unsatisfied. +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. @@ -26,9 +26,9 @@ This package represents the set of libraries which are produced in dotnet/runtim To add a library to the ASP.NETCore shared framework, that library should set the `IsAspNetCoreApp` property for it's `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 be closure complete with respect to both ASP.NETCore shared framework and the .NETCore shared framework. TODO: validate this when building the transport package. +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. +Removing a library from this transport package is a breaking change and should be avoided. ## NuGet package @@ -85,7 +85,7 @@ Build props and targets may be needed in NuGet packages. To define these, autho 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 add include an analyzer in a package, simply add an `AnalyzerReference` item to the project that produces the package that should contain the analyzer -```xml +```xml diff --git a/docs/coding-guidelines/package-projects.md b/docs/coding-guidelines/package-projects.md index a96f57709303c3..3e3caa257344b4 100644 --- a/docs/coding-guidelines/package-projects.md +++ b/docs/coding-guidelines/package-projects.md @@ -1,5 +1,5 @@ # Package projects -** IMPORTANT ** Package projects are in the process of being deprecated, please do nopt create new package projects. Instead use normal projects (csproj) following the guidelines here: [libraries-packaging](libraries-packaging.md) +** 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. diff --git a/src/libraries/Directory.Build.targets b/src/libraries/Directory.Build.targets index 42c6c133998097..27ea3046895ad9 100644 --- a/src/libraries/Directory.Build.targets +++ b/src/libraries/Directory.Build.targets @@ -318,15 +318,15 @@ set to their location in the package. IsSymbol metadata will be set to distinguish symbols. --> - + - + - <_TargetPathsToSymbols Include="@(_AnalyzerFiles)" TargetPath="/%(_AnalyzerFiles.PackagePath)" Condition="%(_AnalyzerFiles.IsSymbol)" /> + <_TargetPathsToSymbols Include="@(_AnalyzerFile)" TargetPath="/%(_AnalyzerFile.PackagePath)" Condition="%(_AnalyzerFile.IsSymbol)" /> From 691b89569959ce1637e97700b805f2f0a94bffae Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Mon, 10 May 2021 13:35:08 -0700 Subject: [PATCH 3/8] More feedback --- docs/coding-guidelines/libraries-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/coding-guidelines/libraries-packaging.md b/docs/coding-guidelines/libraries-packaging.md index c560aac7c94d61..b9a04d6ce545eb 100644 --- a/docs/coding-guidelines/libraries-packaging.md +++ b/docs/coding-guidelines/libraries-packaging.md @@ -10,7 +10,7 @@ The library should have both a `ref` and `src` project. It's reference assembly 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 it's 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 prefferable to avoid this by choosing to target frameworks which can both ship in the package and shared framework. -If a library should be excluded from the ref-pack and not visible to customers targeting that shared framework, the library may be included in the `NetCoreAppLibraryNoReference` property in [NetCoreAppLibrary.props](../../src/libraries/NetCoreAppLibrary.props). +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. From 863ff03e44501c17fee21e73414b64290c549548 Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Wed, 12 May 2021 14:57:29 -0700 Subject: [PATCH 4/8] Address more feedback --- docs/coding-guidelines/libraries-packaging.md | 34 +++++++++---------- src/libraries/Directory.Build.targets | 3 +- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/coding-guidelines/libraries-packaging.md b/docs/coding-guidelines/libraries-packaging.md index b9a04d6ce545eb..ac1710c25e85c5 100644 --- a/docs/coding-guidelines/libraries-packaging.md +++ b/docs/coding-guidelines/libraries-packaging.md @@ -6,13 +6,13 @@ Libraries can be packaged in one or more of the following ways: as part of the . 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. It's reference assembly will be included in the ref-pack for the Microsoft.NETCore.App shared framework, and it's implementation assembly will be included in the runtime pack. +The library should have both a `ref` and `src` project. It's reference assembly will be included in the ref-pack for the Microsoft.NETCore.App shared framework, and it's 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 it's 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 prefferable to avoid this by choosing to target frameworks which can both ship in the package and shared framework. +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 it's 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. +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. +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. @@ -22,21 +22,21 @@ Transport packages are non-shipping packages that dotnet/runtime produces in ord ### 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. +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 it's `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. +To add a library to the ASP.NETCore shared framework, that library should set the `IsAspNetCoreApp` property for it's `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 +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. +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. +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 need not 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: +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. @@ -54,25 +54,25 @@ Package content can be defined using any of the publicly defined Pack inputs: ht ### TargetFrameworks -By default all TargetFrameworks listed in your project will be included in the package. You may exclude sepecific TargetFrameworks by setting `ExcludeFromPackage` on that framework. +By default all TargetFrameworks listed in your project will be included in the package. You may exclude sepecific 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 +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. +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: +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 @@ -82,16 +82,16 @@ Build props and targets may be needed in NuGet packages. To define these, autho ### 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. +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 add include an analyzer in a package, simply add an `AnalyzerReference` item to the project that produces the package that should contain the analyzer +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. +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 diff --git a/src/libraries/Directory.Build.targets b/src/libraries/Directory.Build.targets index 27ea3046895ad9..0e8b94e2c4115b 100644 --- a/src/libraries/Directory.Build.targets +++ b/src/libraries/Directory.Build.targets @@ -325,7 +325,8 @@ + so a rooted path value for TargetPath will override lib. + https://github.com/NuGet/Home/issues/10860 --> <_TargetPathsToSymbols Include="@(_AnalyzerFile)" TargetPath="/%(_AnalyzerFile.PackagePath)" Condition="%(_AnalyzerFile.IsSymbol)" /> From fc9b4db816e64db1da9c51ec6a8e5988425d0e39 Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Wed, 12 May 2021 14:57:53 -0700 Subject: [PATCH 5/8] Remove src.proj build of generators --- src/libraries/System.Text.Json/src/System.Text.Json.csproj | 3 +++ src/libraries/src.proj | 4 ---- 2 files changed, 3 insertions(+), 4 deletions(-) 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/src.proj b/src/libraries/src.proj index e73626b1ee4598..2a2f28c8567d00 100644 --- a/src/libraries/src.proj +++ b/src/libraries/src.proj @@ -7,12 +7,8 @@ <_allSrc Include="$(MSBuildThisFileDirectory)*\src\*.csproj" Exclude="@(ProjectExclusions)" /> - - - + diff --git a/eng/Version.Details.xml b/eng/Version.Details.xml index 7b3d833bd2affd..e4b9072148674f 100644 --- a/eng/Version.Details.xml +++ b/eng/Version.Details.xml @@ -186,9 +186,9 @@ https://github.com/dotnet/xharness cbd98edd36d8763026152cfee248aeb1537b1d4b - + https://github.com/dotnet/arcade - 01c1af9f5ead4962e390cfbec92396de34118492 + 57707a9e0150de043f8fc4a849f1f4f47dd3219a https://dev.azure.com/dnceng/internal/_git/dotnet-optimization diff --git a/eng/Versions.props b/eng/Versions.props index 9d3af13f3369f7..01b9bcbb036f59 100644 --- a/eng/Versions.props +++ b/eng/Versions.props @@ -62,7 +62,7 @@ 6.0.0-beta.21256.1 6.0.0-beta.21256.1 6.0.0-beta.21256.1 - 6.0.0-beta.21256.1 + 6.0.0-beta.21262.3 5.9.0-preview.2 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 @@ - + From fc4d991a680ed7e61aa683db0b4f674b106ec176 Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Thu, 13 May 2021 11:23:26 -0700 Subject: [PATCH 7/8] Fix typos --- docs/coding-guidelines/libraries-packaging.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/coding-guidelines/libraries-packaging.md b/docs/coding-guidelines/libraries-packaging.md index ac1710c25e85c5..caf447ca598a10 100644 --- a/docs/coding-guidelines/libraries-packaging.md +++ b/docs/coding-guidelines/libraries-packaging.md @@ -4,11 +4,11 @@ Libraries can be packaged in one or more of the following ways: as part of the . ## .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) +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. It's reference assembly will be included in the ref-pack for the Microsoft.NETCore.App shared framework, and it's implementation assembly will be included in the runtime pack. +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 it's 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. +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. @@ -24,7 +24,7 @@ Transport packages are non-shipping packages that dotnet/runtime produces in ord 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 it's `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. +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 @@ -54,7 +54,7 @@ Package content can be defined using any of the publicly defined Pack inputs: ht ### TargetFrameworks -By default all TargetFrameworks listed in your project will be included in the package. You may exclude sepecific TargetFrameworks by setting `ExcludeFromPackage` on that framework. +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 From c33bfc7e1d3f03cc174a9c753c36012bf6fdb3d1 Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Thu, 13 May 2021 11:17:57 -0700 Subject: [PATCH 8/8] Fix package testing on net46* --- src/libraries/pkg/test/frameworkSettings/net/settings.targets | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/libraries/pkg/test/frameworkSettings/net/settings.targets b/src/libraries/pkg/test/frameworkSettings/net/settings.targets index e4e8ff23d6855f..30b04a6dee3b01 100644 --- a/src/libraries/pkg/test/frameworkSettings/net/settings.targets +++ b/src/libraries/pkg/test/frameworkSettings/net/settings.targets @@ -89,6 +89,9 @@ + + +