Improve usability of APICompat (#2672)

* Improve usability of APICompat * Improve API Compat README.md
dotnet · May 7, 2019 · c31fac9 · c31fac9
1 parent d970269
commit c31fac9
Show file tree

Hide file tree

Showing 2 changed files with 80 additions and 25 deletions.
diff --git a/src/Microsoft.DotNet.ApiCompat/README.md b/src/Microsoft.DotNet.ApiCompat/README.md
@@ -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)`.
+
+`$(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.
diff --git a/src/Microsoft.DotNet.ApiCompat/build/Microsoft.DotNet.ApiCompat.targets b/src/Microsoft.DotNet.ApiCompat/build/Microsoft.DotNet.ApiCompat.targets
@@ -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)')" />
@@ -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>
@@ -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">
@@ -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>
@@ -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>
@@ -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">
@@ -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>