VSadov/Satori
1
0
Fork 0
mirror of https://github.com/VSadov/Satori.git synced 2025-06-08 11:37:04 +09:00
Code Activity
Satori/docs/coding-guidelines/updating-ref-source.md
Alexander Köplinger 8762a02634
Add reference assembly for System.Private.CoreLib.dll (#72143) 
We now compile against the reference assembly in all places where we were compiling against the mono/coreclr System.Private.CoreLib.dll implementation assembly before.

The new reference assembly consumes sources from the existing contracts to avoid checking in a generated version of SPC.dll (this would add ~20k lines of .cs which is mostly duplicated with System.Runtime.cs)

Since a few contracts have only partially moved types to SPC we wrap contract types with `#if !BUILDING_CORELIB_REFERENCE` so we can hide them when compiling the SPC reference assembly. This needed a few GenAPI changes which are implemented here: https://github.com/dotnet/arcade/pull/10003.

Note that this means that the types which live in CoreLib are moved to the end of the ref .cs file which causes a GitHub diff to show up, but it is actually a no-op.

Regenerating the ref .cs files works the same way as before, by running the `GenerateReferenceAssemblySource` target in the contract's src\ folder.

Fixes https://github.com/dotnet/runtime/issues/67660

Co-authored-by: Viktor Hofer <viktor.hofer@microsoft.com>
2022-08-02 17:58:13 +02:00

2.5 KiB
Raw Blame History

This document provides the steps you need to take to update the reference assembly when adding new public APIs to an implementation assembly (post API Review).

For most assemblies within libraries

  1. Implement the API in the source assembly and build it. Note that when adding new public types, this might fail with a TypeMustExist error. The deadlock can be worked around by disabling the RunApiCompat property: dotnet build /p:RunApiCompat=false.
  2. Run the following command (from the src directory) dotnet msbuild /t:GenerateReferenceAssemblySource to update the reference assembly**.
  3. Navigate to the ref directory and build the reference assembly.
  4. Add, build, and run tests.

** Note: If you already added the new API to the reference source, re-generating it (after building the source assembly) will update it to be fully qualified and placed in the correct order. This can be done by running the GenerateReferenceAssemblySource command from the ref directory.

For System.Runtime

These steps can also be applied to some unique assemblies which depend on changes in System.Private.Corelib. (partial facades like System.Memory, for example).

  1. Run dotnet build --no-incremental /t:GenerateReferenceAssemblySource from the System.Runtime/src directory.
  2. Filter out all unrelated changes and extract the changes you care about (ignore certain attributes being removed). Generally, this step is not required for other reference assemblies.

For Full Facade Assemblies implementation assemblies

For implementation assemblies that are "full facades" over another assembly but define types in the reference assembly (ex. System.Runtime.Serialization.Json or System.Xml.XDocument), use the following command to generate the reference source code instead:

dotnet msbuild /t:GenerateReferenceAssemblySource /p:GenAPIFollowTypeForwards=true

For .NETFramework Facade Assemblies

Some assemblies define types in .NETStandard and .NETCore but require facades on .NETFramework to forward types to their existing location in .NETFramework. In these cases we need to add type forwards manually to the .NETFramework build of the reference assembly. TypeForwards must be added for every type in the compatible .NETStandard reference assembly that exists in the .NETFramework, types which are defined in the .NETFramework reference should be factored into a shared source file.