CoreFx build changes for .NETStandard2.0

netstandard20-corefx-infra.md

##dotnet/CoreFx ###Libraries in NETStandard

• ref
  • Default targetgroup should be NETCoreApp build
  • P2P references to other reference assembly CSProjs.
  • System.Runtime core assembly.
  • Cross-compiles for concrete frameworks (if different)
    • EG: exposes types/members not in NETStandard on NETCoreApp, but not on UWP
• src
  • Default targetgroup should be NETCoreApp build
  • depends on System.Runtime?
    • Yes: P2P to ref CSProjs
    • No: P2P to implementation projects
  • Issue: what if dependency is not in NETStandard? EG: Buffers
    • P2P reference to pkgproj
    • Reference to NETStandard.dll facade for NETCoreApp
• pkg
  • No individual package builds.
  • We will have a single package for all of NETCore.App's netstandard.library implementation. Below TBD.
    • framework split packages
      • ref\netcoreappN - all refs for NETCoreApp,Version=vN
    • runtime split packages
      • runtime{RID}\lib\netcoreappN - all impl for NETCoreApp,Version=vN, cross-gen'ed for RID
• tests
  • By default get all of NETStandard.Library for a specific version that they target (auto-referenced by targets)
  • Use P2P references to pkgproj for things not in NETStandard.Library
  • Implementation is automatically injected by targets.

###Libraries above NETStandard

• ref
  • Only required if component is inbox somewhere or has multiple implementations for same NETStandard version.
  • Build against NETStandard.Library package
  • P2P references to pkgproj for things not in NETStandard.Library
  • For builds that support older platforms (eg: netstandard1.0-1.6) we'll be building against the older contract-based NETStandard, we will need a story for this for build-from-source.
• src
  • Build against NETStandard.Library package
  • P2P references to pkgproj for things not in NETStandard.Library
  • For builds that support older platforms (eg: netstandard1.0-1.6) we'll be building against the older contract-based NETStandard, we will need a story for this for build-from-source.
• pkg
  • Not in NETCore.App: as today
  • In NETCore.App: package in NETCore.App package as above
    • If the library also ships in a package, it will also build a package as today. This package may or may-not include the same binaries as are used by NETCore.App, for instance if the library builds against older NETStandard versions.
• tests
  • By default get all of NETStandard.Library for a specific version that they target (auto-referenced by targets)
  • Use P2P references for things not in NETStandard.Library
  • Implementation is automatically injected by targets.

###NETStandard compatibility facade Provides compatibility between NETCore.App and libraries built against NETStandard.

• ref
  • Should adapt supported NETStandard.dll to contract reference assemblies.
  • EG: GenFacades -contracts:<netstandard.dll> -seeds:<allNetCoreAppReferenceAssemblies>
• src
  • Should adapt supported NETStandard.dll to implementation assemblies.
  • EG: GenFacades -contracts:<netstandard.dll> -seeds:<allNetCoreAppImplementationAssemblies>
• pkg
  • No individual package builds.
  • Should be included in NETCoreApp package as above

###Desktop compatibility facades

• ref
  • Should adapt latest desktop surface to contract reference assemblies for anything that has type-overlap with desktop, including assemblies like Microsoft.Win32.Registry which are not in NETStandard.Library.
  • EG: GenFacades -contracts:<desktopReferenceAssemblies> -seeds:<allNetCoreAppReferenceAssemblies>
• src
  • Should adapt latest desktop surface to netcore app implementation for anything that has type-overlap with desktop, including assemblies like Microsoft.Win32.Registry which are not in NETStandard.Library.
  • EG: GenFacades -contracts:<desktopReferenceAssemblies> -seeds:<allNetCoreAppImplementationAssemblies>
• pkg
  • No individual package builds.
  • Should be included in NETCoreApp package as above

###Native shims

• pkg
  • No individual package builds.
  • As with libraries in NETStandard the shims will be included in the runtime specific packages for NETCoreApp

##Transition

###End goal

• CoreFx does not build any reference assemblies for NETStandard.
• For every library in NETStandard.Library, the only configurations in CoreFx are framework-specific. EG: NETCoreApp1.2, UAP10.1
• For every library in NETCore.App but not in NETStandard.Library there must be a framework-specific configuration for NETCoreApp1.2. Other configurations may exist to ship in a package, but those will not be built by folks building just NETCore.App.

###Getting there (WIP)

Folks still consume our current packages so we need to keep building those until we transition.

1. Create a new NETCore.App package: Microsoft.Private.CoreFx.NETCore.App. This will be an identity package with every ref that targets NETCore.App and runtime-specific packages that have all runtime impl's that apply to NETCore.App.
2. Filter the content of Microsoft.Private.CoreFx.NETCore.App to just the things that are part of NETCore, and their closure.
3. Transition tests to use Microsoft.Private.CoreFx.NETCore.App.
4. Delete packages for things that are only part of Microsoft.Private.CoreFx.NETCore.App and don't ship independently.

• Delete configurations for libraries that are no longer used
• As packages are deleted we'll need to opt-in to Microsoft.Private.CoreFx.NETCore.App in some way.
  • proposal:
    • each CSProj is evaluated for layout path in the context of all of its build configurations.
    • We'll determine applicability similar to how we do for pkgprojs to idenitify which config to binplace.

I like this plan, it aligns with how I've been thinking about changing the build, and ive been playing around with similar changes with respect to building ref and src for libraries in netstandard. Let's sync up soon. Thanks for capturing this info.

/cc @ellismg

@ericstj I think there are some markdown formatting issues around the GenFacades steps (the stuff in the <...> blocks is being treated as HTML).

For the tests, when you say "implementation is automatically injected by targets" I assume that means the live version of the libraries that were just built instead of using some LKG build (modulo dependencies from outside the repository like CoreCLR/CoreRT/Desktop)?

For libraries that target older versions of netstandard, I would assume they would have package dependencies on older packages. Is it possible that the "netstandard" repository could build these packages (with just refs?) from source? E.g. imagine netstandard had a bunch of branches or tags: release/netstandard1.0, release/netstandard1.1, etc, and building these branches/tags produces the correct version of all the factored packages at the correct version but which only contained the refs?

We could use that package to build both the ref and src projects. For tests there would be be ok running the unit tests using the "live" versions of all the other assemblies (e.g. you depend on System.Runtime 4.0.0.0 but at runtime you get 4.2.0.0, which is the version built by corefx), or do we need to support running tests for this stuff on a platform that looks exactly like .NET Core for NS 1.X?

Regarding target groups, do you have a thought as to what the set we'd have looks like? Do we still use the "default" target group as today or is that gone?

"implementation is automatically injected by targets" I assume that means the live version of the libraries that were just built instead of using some LKG build

Correct. We want to use the live build. I don't think we need to make the tests reference everything they use, but we can discuss that. There's also a case for tests that test NETCoreApp-specific API. In that case the tests will need to compile against contract refs instead of netstandard. We'll probably need to split tests apart to accomodate this.

For libraries that target older versions of netstandard, I would assume they would have package dependencies on older packages. Is it possible that the "netstandard" repository could build these packages (with just refs?) from source? E.g. imagine netstandard had a bunch of branches or tags: release/netstandard1.0, release/netstandard1.1, etc, and building these branches/tags produces the correct version of all the factored packages at the correct version but which only contained the refs?

That's an interesting suggestion. I've been discussing with @terrajobst how we want to handle the older versions. We were thinking about using the old packages rather than the raw dlls, primarily for compat: folks expect to get implementations when referencing NETStandard.Library from a NETCoreApp1.0 standalone app. I still think it's reasonable to stand up source code that builds the previous versions. That's a one-time thing and we could build potentially build it with a different identity.

For TargetGroups I expect we'll have something similar to what we have today. The difference will be that most of the desktop builds will move to the standard repo since they're pure facades that only changes when netstandard changes. We'll still want to be able to build NETCoreApp, UWP, and (upcoming) CoreRT builds out of CoreFX, as well as some older netstandard builds for things that target netstandard. Perhaps we with TargetGroup='' we could be more specific about it and make it always mean NETCoreApp.