Skip to content

Update convention how to ref&pkg an analyzer again #69237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ViktorHofer wants to merge 2 commits into from
Closed

Update convention how to ref&pkg an analyzer again #69237

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2d8d159
Update convention how to ref&pkg an analyzer again
ViktorHofer May 12, 2022
c91a7f9
Update generators.targets
ViktorHofer May 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions docs/coding-guidelines/libraries-packaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Such transport packages represent the set of libraries which are produced in dot

To add a library to the target's shared framework, that library should be listed in the `AspNetCoreAppLibrary` or `WindowsDesktopAppLibrary` section in `NetCoreAppLibrary.props`.

Source generators and analyzers can be included in the package by adding them to the `Microsoft.Internal.Runtime.**TARGET**.Transport.proj` as an AnalyzerReference. The analyzer projects should specify `AnalyzerLanguage` as mentioned [below](#analyzers--source-generators).
Source generators and analyzers can be included in the package by adding them to the `Microsoft.Internal.Runtime.**TARGET**.Transport.proj` as a ProjectReference with the `ReferenceOutputAssembly=false` and `PackAsAnalyzer=true` metadata set. The analyzer projects should specify `AnalyzerLanguage` as mentioned [below](#analyzers--source-generators).

Libraries included in this transport package should ensure all direct and transitive assembly references are also included in either the target's shared framework or the Microsoft.NETCore.App shared framework. This is not validated in dotnet/runtime at the moment: https://github.com/dotnet/runtime/issues/52562

Expand Down Expand Up @@ -70,10 +70,13 @@ Build props and targets may be needed in NuGet packages. To define these, author

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 and set the `Pack` metadata to true. If you just want to include the analyzer but not consume it, set the `ReferenceAnalyzer` metadata to false.
To include an analyzer in a package, simply add a `ProjectReference` item to the project that produces the package that should contain the analyzer and set the `ReferenceOutputAssembly` metadata to false and the `PackAsAnalyzer` metadata to true. If you also want to consume the analyzer, set the `OutputItemType` metadata to `Analyzer`.
```xml
<ItemGroup>
<AnalyzerReference Include="..\gen\System.Banana.Generators.csproj" Pack="true" ReferenceAnalyzer="false" />
<ItemGroup>
<!-- Includes the analyzer in the package without consuming it. -->
<ProjectReference Include="..\gen\System.Banana.Generators.csproj" ReferenceOutputAssembly="false" PackAsAnalyzer="true" />
<!-- Includes the analyzer in the package and consumes it. -->
<ProjectReference Include="..\gen\System.Banana.Generators.csproj" ReferenceOutputAssembly="false" OutputItemType="Analyzer" PackAsAnalyzer="true" />
</ItemGroup>
```

Expand Down
2 changes: 1 addition & 1 deletion docs/coding-guidelines/project-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ All test outputs should be under

## gen
In the gen directory any source generator related to the assembly should exist. This does not mean the source generator is only used for that assembly only that it is conceptually apart of that assembly. For example, the assembly may provide attributes or low-level types the source generator uses.
To consume a source generator, simply add an `<AnalyzerReference Include="..." />` item to the project, usually next to the `References` and `ProjectReferences` items.
To consume a source generator, simply add a `<ProjectReference Include="..." ReferenceOutputAssembly="false" OutputItemType="Analyzer" />` item to the project.

## Facades
Facade are unique in that they don't have any code and instead are generated by finding a contract reference assembly with the matching identity and generating type forwards for all the types to where they live in the implementation assemblies (aka facade seeds). There are also partial facades which contain some type forwards as well as some code definitions. All the various build configurations should be contained in the one csproj file per library.
Expand Down
14 changes: 3 additions & 11 deletions eng/generators.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,18 +41,10 @@
That is required as the EnabledGenerators condition checks on the Reference and ProjectReference items and hence can't be a property condition. -->
<ItemGroup Condition="'@(EnabledGenerators)' != '' and
@(EnabledGenerators->AnyHaveMetadataValue('Identity', 'LibraryImportGenerator'))">
<AnalyzerReference Include="$(LibrariesProjectRoot)System.Runtime.InteropServices\gen\LibraryImportGenerator\LibraryImportGenerator.csproj;
$(LibrariesProjectRoot)System.Runtime.InteropServices\gen\Microsoft.Interop.SourceGeneration\Microsoft.Interop.SourceGeneration.csproj" />
</ItemGroup>

<!-- AnalyzerReference items are transformed to ProjectReferences with the required analyzer metadata. -->
<ItemGroup>
<ProjectReference Include="@(AnalyzerReference)"
<ProjectReference Include="$(LibrariesProjectRoot)System.Runtime.InteropServices\gen\LibraryImportGenerator\LibraryImportGenerator.csproj;
$(LibrariesProjectRoot)System.Runtime.InteropServices\gen\Microsoft.Interop.SourceGeneration\Microsoft.Interop.SourceGeneration.csproj"
ReferenceOutputAssembly="false"
OutputItemType="Analyzer"
Pack="false" />
<ProjectReference Update="@(AnalyzerReference->WithMetadataValue('ReferenceAnalyzer', 'false'))"
OutputItemType="" />
OutputItemType="Analyzer" />
</ItemGroup>

<Target Name="ConfigureGenerators"
Expand Down
8 changes: 4 additions & 4 deletions eng/packaging.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,8 +141,8 @@
These will be returned as items with identity pointing to the built file, and PackagePath metadata
set to their location in the package. IsSymbol metadata will be set to distinguish symbols. -->
<Target Name="IncludeAnalyzersInPackage"
Condition="'@(AnalyzerReference)' != '' and @(AnalyzerReference->AnyHaveMetadataValue('Pack', 'true'))">
<MSBuild Projects="@(AnalyzerReference->WithMetadataValue('Pack', 'true'))"
Condition="'@(ProjectReference)' != '' and @(ProjectReference->AnyHaveMetadataValue('PackAsAnalyzer', 'true'))">
<MSBuild Projects="@(ProjectReference->WithMetadataValue('PackAsAnalyzer', 'true'))"
Targets="GetAnalyzerPackFiles">
<Output TaskParameter="TargetOutputs" ItemName="_AnalyzerFile" />
</MSBuild>
Expand All @@ -166,8 +166,8 @@
<!-- In packages that contain Analyzers, include a .targets file that will select the correct analyzer. -->
<Target Name="IncludeMultiTargetRoslynComponentTargetsInPackage"
AfterTargets="IncludeAnalyzersInPackage"
Condition="'@(AnalyzerReference)' != '' and
@(AnalyzerReference->AnyHaveMetadataValue('Pack', 'true')) and
Condition="'@(ProjectReference)' != '' and
@(ProjectReference->AnyHaveMetadataValue('PackAsAnalyzer', 'true')) and
'$(IncludeMultiTargetRoslynComponentTargets)' == 'true'"
DependsOnTargets="GenerateMultiTargetRoslynComponentTargetsFile">
<ItemGroup>
Expand Down
14 changes: 7 additions & 7 deletions ...soft.Extensions.Logging.Abstractions/src/Microsoft.Extensions.Logging.Abstractions.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,13 +37,13 @@ Microsoft.Extensions.Logging.Abstractions.NullLogger</PackageDescription>
</ItemGroup>

<ItemGroup>
<AnalyzerReference Include="..\gen\Microsoft.Extensions.Logging.Generators.Roslyn3.11.csproj"
Pack="true"
ReferenceAnalyzer="false"
Condition="'$(DotNetBuildFromSource)' != 'true'" />
<AnalyzerReference Include="..\gen\Microsoft.Extensions.Logging.Generators.Roslyn4.0.csproj"
Pack="true"
ReferenceAnalyzer="false" />
<ProjectReference Include="..\gen\Microsoft.Extensions.Logging.Generators.Roslyn3.11.csproj"
ReferenceOutputAssembly="false"
PackAsAnalyzer="true"
Condition="'$(DotNetBuildFromSource)' != 'true'" />
<ProjectReference Include="..\gen\Microsoft.Extensions.Logging.Generators.Roslyn4.0.csproj"
ReferenceOutputAssembly="false"
PackAsAnalyzer="true" />
</ItemGroup>

</Project>
6 changes: 3 additions & 3 deletions ...nal.Runtime.AspNetCore.Transport/src/Microsoft.Internal.Runtime.AspNetCore.Transport.proj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@
Private="true"
IncludeReferenceAssemblyInPackage="true" />
<!-- Only include the 4.0 version in the ref pack, since targeting net6.0 requires Roslyn 4.0 -->
<AnalyzerReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Logging.Abstractions\gen\Microsoft.Extensions.Logging.Generators.Roslyn4.0.csproj"
Pack="true"
ReferenceAnalyzer="false" />
<ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Logging.Abstractions\gen\Microsoft.Extensions.Logging.Generators.Roslyn4.0.csproj"
ReferenceOutputAssembly="false"
PackAsAnalyzer="true" />
</ItemGroup>
</Project>
2 changes: 1 addition & 1 deletion ...raries/System.ComponentModel.TypeConverter/src/System.ComponentModel.TypeConverter.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@
</ItemGroup>

<ItemGroup>
<AnalyzerReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" />
<ProjectReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" ReferenceOutputAssembly="false" OutputItemType="Analyzer" />
<Reference Include="System.Collections" />
<Reference Include="System.Collections.NonGeneric" />
<Reference Include="System.Collections.Specialized" />
Expand Down
2 changes: 1 addition & 1 deletion ...tem.Private.DataContractSerialization/src/System.Private.DataContractSerialization.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@
</ItemGroup>

<ItemGroup>
<AnalyzerReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" />
<ProjectReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" ReferenceOutputAssembly="false" OutputItemType="Analyzer" />
<Reference Include="System.Collections" />
<Reference Include="System.Collections.Concurrent" />
<Reference Include="System.Collections.NonGeneric" />
Expand Down
2 changes: 1 addition & 1 deletion src/libraries/System.Private.Xml/src/System.Private.Xml.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -760,7 +760,7 @@
</ItemGroup>

<ItemGroup>
<AnalyzerReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" />
<ProjectReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" ReferenceOutputAssembly="false" OutputItemType="Analyzer" />
<Reference Include="System.Collections" />
<Reference Include="System.Collections.Concurrent" />
<Reference Include="System.Collections.NonGeneric" />
Expand Down
3 changes: 1 addition & 2 deletions src/libraries/System.Runtime/tests/System.Runtime.Tests.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,11 +305,10 @@
</ItemGroup>

<ItemGroup>
<AnalyzerReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" />

<PackageReference Include="Moq" Version="$(MoqVersion)" />
<PackageReference Include="System.Runtime.Numerics.TestData" Version="$(SystemRuntimeNumericsTestDataVersion)" GeneratePathProperty="true" />

<ProjectReference Include="$(LibrariesProjectRoot)System.Text.RegularExpressions\gen\System.Text.RegularExpressions.Generator.csproj" ReferenceOutputAssembly="false" OutputItemType="Analyzer" />
<ProjectReference Include="TestLoadAssembly\TestLoadAssembly.csproj" />
<ProjectReference Include="TestCollectibleAssembly\TestCollectibleAssembly.csproj" />
<ProjectReference Include="TestModule\System.Reflection.TestModule.ilproj" />
Expand Down
14 changes: 7 additions & 7 deletions src/libraries/System.Text.Json/src/System.Text.Json.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -381,12 +381,12 @@ System.Text.Json.Nodes.JsonValue</PackageDescription>
</ItemGroup>

<ItemGroup>
<AnalyzerReference Include="..\gen\System.Text.Json.SourceGeneration.Roslyn3.11.csproj"
Pack="true"
ReferenceAnalyzer="false"
Condition="'$(DotNetBuildFromSource)' != 'true'" />
<AnalyzerReference Include="..\gen\System.Text.Json.SourceGeneration.Roslyn4.0.csproj"
Pack="true"
ReferenceAnalyzer="false" />
<ProjectReference Include="..\gen\System.Text.Json.SourceGeneration.Roslyn3.11.csproj"
ReferenceOutputAssembly="false"
PackAsAnalyzer="true"
Condition="'$(DotNetBuildFromSource)' != 'true'" />
<ProjectReference Include="..\gen\System.Text.Json.SourceGeneration.Roslyn4.0.csproj"
ReferenceOutputAssembly="false"
PackAsAnalyzer="true" />
</ItemGroup>
</Project>