Add reference assembly build (#1014)

* Add reference assembly build

This adds a new project that builds a reference assembly for some of
the surface area of the linker. The package is called illink. We
should finalize the name before releasing an official package. This
leaves a number of problems unsolved (described below), but provides
something we can use to start experimenting.

The preliminary included surface area contains public members of
BaseStep and its dependencies, in the FEATURE_ILLINK build flavor -
which notably makes the ref assembly incompatible with the monolinker
surface area. (illink has an AssemblyResolver derived from
Mono.Linker.DirectoryAssemblyResolver, whereas monolinker has one
derived from Mono.Cecil.BaseAssemblyResolver). Therefore the reference
assembly is currently designed for consumption by illink plugins, not
by monolinker plugins.

The reference assembly is built for netstandard2.0, chosen because it
is the lowest common denominator for netcoreapp3.0 and net471, the
TFMs for which we currently build Mono.Linker. The illink flavor
actually doesn't need to be built for net471 (only ILLink.Tasks does),
so we could choose a higher version of netstandard if we disabled that
build flavor.

The ref assembly package is unusual in a few ways, described below. We
may be able to change some of these quirks once we have a better
picture of how linker plugins will be produced and consumed.

- The package *does not* contain any implementation assemblies,
because it is not designed to be consumed by a project targeting a
platform TFM - rather it is only designed to be consumed
from *libraries* that will act as linker plugins. Attempting to
consume it directly from a netcoreapp3.0 project will work during
build, but will fail to locate illink.dll at runtime.

- The package *does not* have a transitive package dependency on
Mono.Cecil (nor does it include Mono.Cecil). This is because the
reference assembly is built against a submodule of the cecil sources,
so we do not have direct control over the package version. This
requires the custom step developer to add a dependency on Mono.Cecil.

To consume this package in a custom step, the custom step project
should:

- Target a netstandard version compatible with the reference
assembly's target framework (currently netstandard2.0).

- Include a dependency on Mono.Cecil compatible with the version
referenced during the linker build (currently 0:11:1:0, which
incidentally ships in the official Mono.Cecil package version
11.1). Attempting to use a higher version (the current latest release
is 11.2) will result in the linker failing to load the custom step.

* Add cecil to the package

This adds a new project which builds reference assemblies for
cecil. It should be kept in sync with the upstream cecil project
file. The cecil reference assembly is included into the illink package
alongside the illink.dll reference assembly.

Also prevent arcade from trying to upload a non-existent PDB for a ref
assembly.

* Set up ApiCompat

* Use .NET Foundation file header

* Pare down ref surface area

- Remove most members of Annotations
- Remove MarkingHelpers and references to it
- Remove protected members of LinkContext
- Remove UninitializedContextFactory and references to it
- Remove AssemblyResolver and references to it

* Fix undefined ExpectedFeedUrl error

The error was occurring because the early import of the Tools targets
was including Microsoft.DotNet.Build.Tasks.Feed.targets, which changed
the DefaultTargets to a publish-related target. Importing the Tools
targets later prevents overriding the DefaultTargets, causing building
to work as expected.

* Add back AnnotationStore ctor

Otherwise the implicitly-defined default ctor exists in the ref but
not the implementation. This was caught by ApiCompat.

* Build against official Mono.Cecil package

This adds an option to build against the submodule for local
development, but the new default is to build against the package.

* Minor project file cleanup

* Remove left-over files

* Further restrict public surface

* Build fix

* UseLocalCecil -> UseCecilPackage

* Use local cecil for monolinker build

* Remove Version from Mono.Linker projects

This will result in the version being taken from VersionPrefix
in Directory.Build.Props, matching the package version.

* Remove left-over reference to cecil ref build

* Copy package dependencies to ILLink.Tasks build output

This preserves the behavior of the ProjectReference dependencies,
which are always copied. The integration tests expect to find the
linker and cecil alongside ILLink.Tasks in the build output.

* Remove AssemblyAction

Co-authored-by: Marek Safar <marek.safar@gmail.com>

1 files changed, 22 insertions, 1 deletions

diff --git a/Directory.Build.props b/Directory.Build.props
index acf6e308c..f85d60a6c 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -2,8 +2,29 @@
   <PropertyGroup>
     <MonoBuild Condition="'$(MonoBuild)' == '' and '$(SolutionName)' == 'monolinker'">true</MonoBuild>
   </PropertyGroup>
+
+  <PropertyGroup>
+    <IsReferenceAssembly Condition="'$(IsReferenceAssembly)' == '' and '$([System.IO.Path]::GetFileName($(MSBuildProjectDirectory)))' == 'ref'">true</IsReferenceAssembly>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(IsReferenceAssembly)' == 'true' ">
+    <ProduceOnlyReferenceAssembly>true</ProduceOnlyReferenceAssembly>
+    <!-- used by Arcade to compute OutputPath, IntermediateOutputPath, etc. early in the import chain. -->
+    <OutDirName>$(MSBuildProjectName)/ref</OutDirName>
+    <!-- don't try to publish PDBs for ref assemblies that have none. -->
+    <PublishWindowsPdb>false</PublishWindowsPdb>
+    <RunApiCompat>false</RunApiCompat>
+  </PropertyGroup>
+
   <Import Project="Sdk.props" Sdk="Microsoft.DotNet.Arcade.Sdk" Condition="'$(MonoBuild)' == ''" />
+  <!-- Still use global versions even if not using arcade. -->
+  <Import Project="eng/Versions.props" Condition="'$(MonoBuild)' != ''" />
   <PropertyGroup>
     <IsPackable>false</IsPackable>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <_ToolsProjectTargets>$(ArtifactsToolsetDir)Common\Tools.proj.nuget.g.targets</_ToolsProjectTargets>
+    <!-- Set this to false to build against the submodule. Convenient for experimenting locally. -->
+    <UseCecilPackage Condition="'$(MonoBuild)' != '' And '$(UseCecilPackage)' == ''">false</UseCecilPackage>
+    <UseCecilPackage Condition="'$(UseCecilPackage)' == ''">true</UseCecilPackage>
   </PropertyGroup>
-</Project>
\ No newline at end of file
+
+</Project>