Skip to content

Improve usability of APICompat #2672

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

Merged
ericstj merged 2 commits into from
May 7, 2019
Merged

Improve usability of APICompat #2672

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
d58450f
Improve usability of APICompat
ericstj May 2, 2019
ec4b3ea
Improve API Compat README.md
ericstj May 3, 2019
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
37 changes: 37 additions & 0 deletions src/Microsoft.DotNet.ApiCompat/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Microsoft.DotNet.ApiCompat

APICompat is a tool which may be used to test API compatibility between a two .NET assemblies.

When testing, the tool will compare a *contract* to an *implementation*.

The *contract* represents the API that's expected : for example a reference assembly or a previous version of an assembly.

The *implementation* represents the API that's provided : for example the current version of an assembly.

## Usage

API Compat can be used by referencing this Microsoft.DotNet.ApiCompat package from the *implementation* project, and providing the path to the *contract* via a single `@(ResolvedMatchingContract)` item. Dependencies of `@(ResolvedMatchingContract)` must be specified in either `DependencyPaths` metadata on the items themselves or via the `$(ContractDependencyPaths)` property.

When API Compat identifies an error it will log the error and fail the build. If you wish to ignore the error you can copy the error text to a baseline file (see below). Take care when doing this as these errors represent compatibility problems between the *contract* and *implementation*.

## Required setting

`@(ResolvedMatchingContract)` - should point to a single file that represents the contract to validate
%(DependencyPaths) - optional, specifies a semi-colon delimited set of paths that contain the assembly dependencies of this contract
`$(ContractDependencyPaths)` - optional, speicifies a semi-colon delimited set of paths that contain the assembly dependencies of this contract

## Additional settings

`$(RunApiCompat)` - true to run APICompat, defaults to true
`$(RunApiCompatForSrc)` - true to run APICompat treating project output as *implementation* and `@(ResolvedMatchingContract)` as *contract*, defaults to true.
`$(RunMatchingRefApiCompat)` - true to run APICompat treating project output as *contract* and `@(ResolvedMatchingContract)` as *implementation*, defaults to true. This is also known as reverse API compat and can help ensure that every public API defined in a project is exposed in `@(ResolvedMatchingContract)`.
Comment thread
ericstj marked this conversation as resolved.

`$(ApiCompatExcludeAttributeList)` - Attributes to exclude from APICompat checks. This is a text file containing types in DocID format, EG: T:Namespace.TypeName.
`$(ApiCompatEnforceOptionalRules)` - true to enforce optional rules, default is false. An example of an optional rule is parameter naming which can break source compatibility but not binary compatibility.


`$(ApiCompatBaseline)` - path to baseline file used to suppress errors, defaults to a file in the project directory.
`$(BaselineAllAPICompatError)` - true to indicate that the baseline file should be rewritten suppressing all API compat errors. You may set this when building the project to conveniently update the baseline when you wish to suppress them, eg: `dotnet msbuild /p:BaselineAllAPICompatError=true`

`$(MatchingRefApiCompatBaseline)` - same as `$(ApiCompatBaseline)` but for reverse API compat.
`$(BaselineAllMatchingRefApiCompatError)` - same as `$(BaselineAllAPICompatError)` but for reverse API compat.
68 changes: 43 additions & 25 deletions src/Microsoft.DotNet.ApiCompat/build/Microsoft.DotNet.ApiCompat.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,35 +12,44 @@
<_ApiCompatCommand Condition="'$(MSBuildRuntimeType)' == 'core'">$(ToolHostCmd) "$(_ApiCompatPath)"</_ApiCompatCommand>
<_ApiCompatCommand Condition="'$(MSBuildRuntimeType)' != 'core' and '$(OS)' == 'Windows_NT'">"$(_ApiCompatPath)"</_ApiCompatCommand>
<_ApiCompatCommand Condition="'$(MSBuildRuntimeType)' != 'core' and '$(OS)' != 'Windows_NT'">mono --runtime=v4.0.30319 "$(_ApiCompatPath)"</_ApiCompatCommand>

<_ApiCompatSemaphoreFile>$(MSBuildThisFileName).semaphore</_ApiCompatSemaphoreFile>
</PropertyGroup>

<PropertyGroup>
<RunApiCompat Condition="'$(RunApiCompat)' == ''">false</RunApiCompat>
<!-- Default is to run API Compat if this package is referenced -->
<RunApiCompat Condition="'$(RunApiCompat)' == ''">true</RunApiCompat>

<RunApiCompatForSrc Condition="'$(RunApiCompatForSrc)' == ''">$(RunApiCompat)</RunApiCompatForSrc>
<RunMatchingRefApiCompat Condition="'$(RunMatchingRefApiCompat)' == ''">false</RunMatchingRefApiCompat>
</PropertyGroup>

<PropertyGroup Condition="'$(RunApiCompat)' == 'true'">
<ApiCompatBaseline Condition="!Exists('$(ApiCompatBaseline)')">$(MSBuildProjectDirectory)\ApiCompatBaseline.$(TargetGroup).txt</ApiCompatBaseline>
<_apiCompatTargetSuffix>$(TargetGroup)</_apiCompatTargetSuffix>
<_apiCompatTargetSuffix Condition="'$(_apiCompatTargetSuffix)' == ''">$(TargetFramework)</_apiCompatTargetSuffix>

<ApiCompatBaseline Condition="!Exists('$(ApiCompatBaseline)')">$(MSBuildProjectDirectory)\ApiCompatBaseline.$(_apiCompatTargetSuffix).txt</ApiCompatBaseline>
<ApiCompatBaseline Condition="!Exists('$(ApiCompatBaseline)')">$(MSBuildProjectDirectory)\ApiCompatBaseline.txt</ApiCompatBaseline>

<MatchingRefApiCompatBaseline Condition="!Exists('$(MatchingRefApiCompatBaseline)')">$(MSBuildProjectDirectory)\MatchingRefApiCompatBaseline.$(TargetGroup).txt</MatchingRefApiCompatBaseline>
<MatchingRefApiCompatBaseline Condition="!Exists('$(MatchingRefApiCompatBaseline)')">$(MSBuildProjectDirectory)\MatchingRefApiCompatBaseline.$(_apiCompatTargetSuffix).txt</MatchingRefApiCompatBaseline>
<MatchingRefApiCompatBaseline Condition="'$(BaselineAllMatchingRefApiCompatError)' != 'true' and !Exists('$(MatchingRefApiCompatBaseline)')">$(MSBuildProjectDirectory)\MatchingRefApiCompatBaseline.txt</MatchingRefApiCompatBaseline>

<RunApiCompatForSrc Condition="$(MSBuildProjectDirectory.EndsWith('src'))">true</RunApiCompatForSrc>

<RunMatchingRefApiCompat Condition="'$(RunMatchingRefApiCompat)' == ''">$(RunApiCompatForSrc)</RunMatchingRefApiCompat>

<ResolveMatchingContract Condition="'$(RunApiCompatForSrc)' == 'true'">true</ResolveMatchingContract>
<TargetsTriggeredByCompilation Condition="'$(RunApiCompatForSrc)' == 'true'">$(TargetsTriggeredByCompilation);ValidateApiCompatForSrc</TargetsTriggeredByCompilation>
<TargetsTriggeredByCompilation Condition="'$(RunMatchingRefApiCompat)' == 'true'">$(TargetsTriggeredByCompilation);RunMatchingRefApiCompat</TargetsTriggeredByCompilation>
</PropertyGroup>

<ItemGroup>
<CustomAdditionalCompileInputs Condition="Exists('$(IntermediateOutputPath)$(_ApiCompatSemaphoreFile)')" Include="$(IntermediateOutputPath)$(_ApiCompatSemaphoreFile)" />
</ItemGroup>

<!-- ApiCompat for Implementation Assemblies -->
<Target Name="ValidateApiCompatForSrc"
Condition="'$(RunApiCompatForSrc)' == 'true' and '$(RunApiCompat)' == 'true' and '@(ResolvedMatchingContract)' != ''">

<PropertyGroup>
<ReferenceAssembly>@(ResolvedMatchingContract)</ReferenceAssembly>
</PropertyGroup>
Condition="'$(RunApiCompatForSrc)' == 'true' and '$(RunApiCompat)' == 'true'">

<Error Condition="'@(ResolvedMatchingContract)' == ''"
Text="ResolvedMatchingContract item must be specified to run API compat." />
<Error Condition="!Exists('%(ResolvedMatchingContract.FullPath)')"
Text="ResolvedMatchingContract '%(ResolvedMatchingContract.FullPath)' did not exist." />

<ItemGroup>
<_DependencyDirectoriesTemp Include="@(ReferencePath -> '%(RootDir)%(Directory)')" />
Expand All @@ -49,11 +58,12 @@
<_DependencyDirectories Condition="'%(_DependencyDirectoriesTemp.ReferenceSourceTarget)' == 'ProjectReference'" Include="%(_DependencyDirectoriesTemp.Identity)" />
<_DependencyDirectories Condition="'%(_DependencyDirectoriesTemp.ReferenceSourceTarget)' != 'ProjectReference'" Include="%(_DependencyDirectoriesTemp.Identity)" />
<_ContractDependencyDirectories Include="@(ResolvedMatchingContract -> '%(RootDir)%(Directory)')" />
<_ContractDependencyDirectories Include="$(ContractOutputPath)" />
<_ContractDependencyDirectories Include="@(ResolvedMatchingContract -> '%(DependencyPaths)')" />
<_ContractDependencyDirectories Include="$(ContractDependencyPaths)" />
</ItemGroup>

<PropertyGroup>
<ApiCompatArgs>$(ApiCompatArgs) "$(ReferenceAssembly)"</ApiCompatArgs>
<ApiCompatArgs>$(ApiCompatArgs) "@(ResolvedMatchingContract)"</ApiCompatArgs>
<ApiCompatArgs>$(ApiCompatArgs) --contract-depends "@(_ContractDependencyDirectories, ','),"</ApiCompatArgs>
<ApiCompatArgs Condition="'$(ApiCompatExcludeAttributeList)' != ''">$(ApiCompatArgs) --exclude-attributes "$(ApiCompatExcludeAttributeList)"</ApiCompatArgs>
<ApiCompatArgs Condition="'$(ApiCompatEnforceOptionalRules)' == 'true'">$(ApiCompatArgs) --enforce-optional-rules</ApiCompatArgs>
Expand All @@ -69,8 +79,7 @@
<MakeDir Directories="$(IntermediateOutputPath)" />
<WriteLinesToFile File="$(ApiCompatResponseFile)" Lines="$(ApiCompatArgs)" Overwrite="true" />

<Exec Condition="Exists('$(ReferenceAssembly)')"
Command="$(_ApiCompatCommand) @&quot;$(ApiCompatResponseFile)&quot; $(ApiCompatBaselineAll)"
<Exec Command="$(_ApiCompatCommand) @&quot;$(ApiCompatResponseFile)&quot; $(ApiCompatBaselineAll)"
CustomErrorRegularExpression="^[a-zA-Z]+ :"
StandardOutputImportance="Low"
IgnoreExitCode="true">
Expand All @@ -79,16 +88,23 @@

<!--
To force incremental builds to show failures again we are invalidating
one compile input by touching the assembly info file
one compile input.
-->
<Touch Condition="'$(ApiCompatExitCode)' != '0'" Files="$(AssemblyInfoFile)" />
<Touch Condition="'$(ApiCompatExitCode)' != '0'" Files="$(IntermediateOutputPath)$(_ApiCompatSemaphoreFile)" AlwaysCreate="true">
<Output TaskParameter="TouchedFiles" ItemName="FileWrites" />
</Touch>
<Error Condition="'$(ApiCompatExitCode)' != '0'" Text="ApiCompat failed for '$(TargetPath)'" />
</Target>

<!-- Reverse APICompat to verify that the reference assembly has all the APIs that are in the implementation -->
<Target Name="RunMatchingRefApiCompat"
Condition="'$(RunMatchingRefApiCompat)' == 'true' and '$(RunApiCompat)' == 'true' and '@(ReferenceFromRuntime)' == ''" >
Condition="'$(RunMatchingRefApiCompat)' == 'true' and '$(RunApiCompat)' == 'true'" >

<Error Condition="'@(ResolvedMatchingContract)' == ''"
Text="ResolvedMatchingContract item must be specified to run API compat." />
<Error Condition="!Exists('%(ResolvedMatchingContract.FullPath)')"
Text="ResolvedMatchingContract '%(ResolvedMatchingContract.FullPath)' did not exist." />

<PropertyGroup>
<ImplemetnationAssemblyAsContract>@(IntermediateAssembly)</ImplemetnationAssemblyAsContract>
</PropertyGroup>
Expand All @@ -100,7 +116,8 @@
<_ContractDependencyDirectories Condition="'%(_ContractDependencyDirectoriesTemp.ReferenceSourceTarget)' == 'ProjectReference'" Include="%(_ContractDependencyDirectoriesTemp.Identity)" />
<_ContractDependencyDirectories Condition="'%(_ContractDependencyDirectoriesTemp.ReferenceSourceTarget)' != 'ProjectReference'" Include="%(_ContractDependencyDirectoriesTemp.Identity)" />
<_ImplementationDependencyDirectories Include="@(ResolvedMatchingContract -> '%(RootDir)%(Directory)')" />
<_ImplementationDependencyDirectories Include="$(ContractOutputPath)" />
<_ImplementationDependencyDirectories Include="@(ResolvedMatchingContract -> '%(DependencyPaths)')" />
<_ImplementationDependencyDirectories Include="$(ContractDependencyPaths)" />
</ItemGroup>

<PropertyGroup>
Expand All @@ -123,8 +140,7 @@
<MakeDir Directories="$(IntermediateOutputPath)" />
<WriteLinesToFile File="$(MatchingRefApiCompatResponseFile)" Lines="$(MatchingRefApiCompatArgs)" Overwrite="true" />

<Exec Condition="Exists('$(ReferenceAssembly)')"
Command="$(_ApiCompatCommand) @&quot;$(MatchingRefApiCompatResponseFile)&quot; $(MatchingRefApiCompatBaselineAll)"
<Exec Command="$(_ApiCompatCommand) @&quot;$(MatchingRefApiCompatResponseFile)&quot; $(MatchingRefApiCompatBaselineAll)"
CustomErrorRegularExpression="^[a-zA-Z]+ :"
StandardOutputImportance="Low"
IgnoreExitCode="true">
Expand All @@ -133,9 +149,11 @@

<!--
To force incremental builds to show failures again we are invalidating
one compile input by touching the assembly info file
one compile input.
-->
<Touch Condition="'$(MatchingRefApiCompatExitCode)' != '0'" Files="$(AssemblyInfoFile)" />
<Touch Condition="'$(MatchingRefApiCompatExitCode)' != '0'" Files="$(IntermediateOutputPath)$(_ApiCompatSemaphoreFile)" AlwaysCreate="true">
<Output TaskParameter="TouchedFiles" ItemName="FileWrites" />
</Touch>
<Error Condition="'$(MatchingRefApiCompatExitCode)' != '0'" Text="MatchingRefApiCompat failed - The reference assembly doesn't match all the APIs in the implementation for '$(TargetPath)'. To address either fix errors in the reference assembly (referenced as implementation in compat errors for this reverse compat check), add the issues to the baseline file '$(MatchingRefApiCompatBaseline)' or disable this check by setting RunMatchingRefApiCompat=false in this project." />
</Target>

Expand Down