Add spec for workload manifests #120
Conversation
| }, | ||
| // on CI machines, this will only be installed if | ||
| // the app actually targets the armv7a architecture | ||
| "xamarin-android-build-armv7a": { |
There was a problem hiding this comment.
There is clearly a lot of convention at play. That's good, however, it would be good to see that more defined.
There was a problem hiding this comment.
Yeah. This is maybe getting out of the scope of this doc though as it's more about how to structure the packs that make up a workload. Maybe something for an authoring guide?
| @@ -0,0 +1,430 @@ | |||
| # .NET SDK Workload Manifests | |||
|
|
|||
| # Overview | |||
There was a problem hiding this comment.
This is a little off-topic, and I don't have a better place for these feedback, so choosing here.
We've been having some conversations about adopting how to declare workloads that are not explicitly tied to a TFM. ASP.NET Core and Windows Forms are good examples. We've been discussing three models to declare a dependence on such a workload in a project file (using ASP.NET Core as the example):
Sdk="Microsoft.NET.Sdk.Web"UseAspnetCore<Workloads>AspnetCore</Workloads>
It is worth clarifying if these are all equivalent from the perspective of tying a project file to a workload, or if there are semantic or technical differences.
If anyone has a preference for the scheme they would like to see used, independent from my question, please feel free to weigh in.
There was a problem hiding this comment.
Since you asked for people to weigh in, here are a bunch of my thoughts:
As a user, I would strongly prefer that Sdk="Microsoft.NET.Sdk.Web" continue to work in .NET 5, so as to have one less thing to need to change. It obviously needs to be able to work for projects targeting 3.x, since if installing .NET 5 SDK broke building 3.x apps unless you use global.json, people would be upset.
Furthermore, I'm not certain that we want every SDK the users might need to specify to become a unique workload. For example, consider Microsoft.NET.Sdk.Worker. It sets some capabilities, some properties, and enables copying *.config and *.json to the output (since M.E.Hosting applications are likely to want to use appsetting.json). Should that become a separate workload? Realistically it could and probably should just be bundled with whatever lets you build simple console apps, which would surely be included in the default .NET 5 SDK install.
Now perhaps that particular SDK is killed off in favor of incorporating that logic into the core SDK, activated by a property or something. But similar things could obviously exist. Not to mention that third party frameworks will still exist that will have their own Sdk= needed, unless there is a plan to support for third parties creating their own workloads. (Well, presumably they could, but without a pre-installed manifest, they would not get the desired experience.)
Per the resolver spec, the missing workloads are already discovered by a new SDK Resolver when an SDK being imported is found to not be present. I'd expect that would work just as well being triggered by the project file itself.
Granted, that this does complicate resolving. Knowing which SDK pack is needed would not always uniquely resolve to a single workload. How dotnet bundle restore would pick between them is unclear. One advantage of <Workloads>AspnetCore</Workloads> is the ability to explicitly specify the workload by name, which could be used to override the the default workload selection logic if you really wanted something different than it decided. Presumably, something like "dotnet bundle restore --build-only" would be smart enough to see the specified pack is a "dev" one, and look though its extends, find only the build workloads, and install just the packs those need.
There was a problem hiding this comment.
Great feedback. Thanks for taking the time.
First, we don't plan to break the existing syntax. That will continue to work. This conversation is a question of what the new scheme should be.
It's subtle but the topic at hand doesn't really relate to workloads exactly. For example, we already have and plan to continue to use UseWinforms and UseWPF properties. We're still planning to include these two components together in the Windows desktop workload, which will be declared via the net5.0-windows TFM.
It's more complicated with ASP.NET Core since it doesn't have its own TFM. ASP.NET Core will be available within net5.0, however, we don't want it to be required to run any .NET 5.0 app. As a result, we need a specific opt-in gesture. In short, it either can work the new way (with the UseFoo style syntax with the benefit that ASP.NET and WPF, for example, will have a symmetrical experience, or ASP.NET can be different and work the old way.
We talked to the ASP.NET team. They didn't like either option, for opposite reasons. I suspect they will end up going with the UseFoo style syntax so that the platform looks like same for all app types.
Make sense?
There was a problem hiding this comment.
Admittedly your first post in this comment series did not distinguish that WPF would be part of a windows workload, and not a separate one. I’ve not actually used the WindowsDesktop sdk, so had not noticed that it used only properties instead of SDKs to distinguish Winforms and WPF. (Admittedly, since using both in the same project is possible, properties are more ergonomic than using sdks, since sdks would require adding a stand alone sdk element to the file to specify the second one if both were used).
My main objection to UseFoo for scenarios like ASP.NET Core, is that SDKs are already a user exposed concept, so adding a magic property to enable one merely for consistency, just seems to be adding more user exposed concepts. After all, third party SDKs will realistically not be able to take advantage of magic properties to load themselves, but could use Sdk= to do so. (Yeah, technically, there are ways a third party sdk could use a magic property to do this, but only if already installed via an installer/package-manager. It could not benefit from automatic discovery that the sdk is needed but not installed. And third party SDKs hooking themselves into every single build on the system is probably not something you would want to encourage, given how easily doing so could cause weird breakage.)
There was a problem hiding this comment.
There are technical differences between the options, but I think they're rather minor. We should mainly base our decision on the experience.
|
I added a link to this PR in: https://github.com/dotnet/designs/blob/master/accepted/2020/workloads/workloads.md. Would be good to update that content in this PR to the final home of the doc. |
| @@ -0,0 +1,430 @@ | |||
| # .NET SDK Workload Manifests | |||
|
|
|||
| # Overview | |||
There was a problem hiding this comment.
There are technical differences between the options, but I think they're rather minor. We should mainly base our decision on the experience.
| "version": "1.0", | ||
| "kind": "sdk", | ||
| "alias-to": { | ||
| "osx-x64": "foo.sdk.compiler.mac", |
There was a problem hiding this comment.
Is it possible to have different version numbers for the mac and windows compiler packages? What would that look like?
Context: https://docs.microsoft.com/dotnet/core/tutorials/cli-templates-create-template-pack Context: https://github.com/dotnet/templating/wiki Context: dotnet/designs#120 This implements basic Android templates that are contained in a `Microsoft.Android.Templates.nupkg` file. We can define a template pack in `WorkloadManifest.json`: "Microsoft.Android.Templates": { "kind": "template", "version": "@TEMPLATE_PACK_VERSION@" } This allows the workload to locate the `*.nupkg` file in: C:\Program Files\dotnet\template-packs /usr/local/share/dotnet/template-packs Our .NET 6 preview installers simply have to place the `*.nupkg` files in the right place for them to be picked up by `dotnet new`. Some example project templates: dotnet new android --output MyAndroidApp --packageName com.mycompany.myandroidapp dotnet new androidlib --output MyAndroidLibrary dotnet new android-bindinglib --output MyJavaBinding And item templates: dotnet new android-activity --name LoginActivity --namespace MyAndroidApp dotnet new android-layout --name MyLayout --output Resources/layout Note that the `android-bindinglib` template is not a special project type. It has additional help files for writing bindings as we have in the current Xamarin.Android templates. I also updated the `XASdkTests` to `dotnet new` each template and `dotnet build` the resulting output.
Context: https://docs.microsoft.com/dotnet/core/tutorials/cli-templates-create-template-pack Context: https://github.com/dotnet/templating/wiki Context: dotnet/designs#120 This implements basic Android templates that are contained in a `Microsoft.Android.Templates.nupkg` file. We can define a template pack in `WorkloadManifest.json`: "Microsoft.Android.Templates": { "kind": "template", "version": "@TEMPLATE_PACK_VERSION@" } This allows the workload to locate the `*.nupkg` file in: C:\Program Files\dotnet\template-packs /usr/local/share/dotnet/template-packs Our .NET 6 preview installers simply have to place the `*.nupkg` files in the right place for them to be picked up by `dotnet new`. Some example project templates: dotnet new android --output MyAndroidApp --packageName com.mycompany.myandroidapp dotnet new androidlib --output MyAndroidLibrary dotnet new android-bindinglib --output MyJavaBinding And item templates: dotnet new android-activity --name LoginActivity --namespace MyAndroidApp dotnet new android-layout --name MyLayout --output Resources/layout Note that the `android-bindinglib` template is not a special project type. It has additional help files for writing bindings as we have in the current Xamarin.Android templates. I also updated the `XASdkTests` to `dotnet new` each template and `dotnet build` the resulting output.
Context: https://docs.microsoft.com/dotnet/core/tutorials/cli-templates-create-template-pack Context: https://github.com/dotnet/templating/wiki Context: dotnet/designs#120 This implements basic Android templates that are contained in a `Microsoft.Android.Templates.nupkg` file. We can define a template pack in `WorkloadManifest.json`: "Microsoft.Android.Templates": { "kind": "template", "version": "@TEMPLATE_PACK_VERSION@" } This allows the workload to locate the `*.nupkg` file in: C:\Program Files\dotnet\template-packs /usr/local/share/dotnet/template-packs Our .NET 6 preview installers simply have to place the `*.nupkg` files in the right place for them to be picked up by `dotnet new`. Some example project templates: dotnet new android --output MyAndroidApp --packageName com.mycompany.myandroidapp dotnet new androidlib --output MyAndroidLibrary dotnet new android-bindinglib --output MyJavaBinding And item templates: dotnet new android-activity --name LoginActivity --namespace MyAndroidApp dotnet new android-layout --name MyLayout --output Resources/layout Note that the `android-bindinglib` template is not a special project type. It has additional help files for writing bindings as we have in the current Xamarin.Android templates. I also updated the `XASdkTests` to `dotnet new` each template and `dotnet build` the resulting output. Finally, the `<GenerateWixFile/>` task (68be8d8) will now add `<Directory/>` entries such as: <Directory Id="packs" Name="packs" FileSource="C:\Users\myuser\android-toolchain\dotnet\packs"> and: <Directory Id="templatepacks" Name="template-packs" FileSource="C:\Users\myuser\android-toolchain\dotnet\template-packs"> <Component Id="SC983E605827BDDA589CA4DFF082E29CDFEC2CD059B4AF3C01421CC95568A8D74"> <File Id="SC983E605827BDDA589CA4DFF082E29CDFEC2CD059B4AF3C01421CC95568A8D74" Name="Microsoft.Android.Templates.11.0.100-ci.dotnet-new.259.nupkg" KeyPath="yes" /> </Component> </Directory> In the latter case, MSI has weird rules around the `Id` value. Consequently, file hashes were used.
Context: https://docs.microsoft.com/dotnet/core/tutorials/cli-templates-create-template-pack Context: https://github.com/dotnet/templating/wiki Context: dotnet/designs#120 Fixes: xamarin#10252 To implement templates in a .NET workload: 1. Make `.nupkg` files that follow the structure of the `dotnet new` templating system, using `$(PackageType)` of `Template`. 2. Install the `.nupkg` files in in `dotnet/template-packs/` 3. Update `WorkloadManifest.json`, to be part of the workload: "Microsoft.@platform@.Templates": { "kind": "template", "version": "@Version@" } These are a starting point, for what I would consider the minimum for the xamarin-macios repo to provide for now: Template Name Short Name Language Tags -------------------------------------------- -------------- ---------- ---------------------- MacCatalyst Application maccatalyst [C#] MacCatalyst iOS Controller template ios-controller [C#] iOS iOS Application ios [C#] iOS iOS Class library ioslib [C#] iOS macOS Application macos [C#] macOS tvOS Application tvos [C#] tvOS We will probably need PM input on what the final templates will be. To use these, you might do: $ mkdir MyApp && cd MyApp $ dotnet new ios $ dotnet new ios-controller --name LoginController --namespace MyApp Co-authored-by: Rolf Bjarne Kvinge <[email protected]>
Context: https://docs.microsoft.com/dotnet/core/tutorials/cli-templates-create-template-pack Context: https://github.com/dotnet/templating/wiki Context: dotnet/designs#120 Fixes: xamarin#10252 To implement templates in a .NET workload: 1. Make `.nupkg` files that follow the structure of the `dotnet new` templating system, using `$(PackageType)` of `Template`. 2. Install the `.nupkg` files in in `dotnet/template-packs/` 3. Update `WorkloadManifest.json`, to be part of the workload: "Microsoft.@platform@.Templates": { "kind": "template", "version": "@Version@" } These are a starting point, for what I would consider the minimum for the xamarin-macios repo to provide for now: Template Name Short Name Language Tags -------------------------------------------- -------------- ---------- ---------------------- iOS Controller template ios-controller [C#] iOS iOS Application ios [C#] iOS iOS Class library ioslib [C#] iOS macOS Application macos [C#] macOS MacCatalyst Application maccatalyst [C#] macOS/Catalyst tvOS Application tvos [C#] tvOS We will probably need PM input on what the final templates will be. To use these, you might do: $ mkdir MyApp && cd MyApp $ dotnet new ios $ dotnet new ios-controller --name LoginController --namespace MyApp Co-authored-by: Rolf Bjarne Kvinge <[email protected]>
Context: https://docs.microsoft.com/dotnet/core/tutorials/cli-templates-create-template-pack Context: https://github.com/dotnet/templating/wiki Context: dotnet/designs#120 Fixes: #10252 To implement templates in a .NET workload: 1. Make `.nupkg` files that follow the structure of the `dotnet new` templating system, using `$(PackageType)` of `Template`. 2. Install the `.nupkg` files in in `dotnet/template-packs/` 3. Update `WorkloadManifest.json`, to be part of the workload: "Microsoft.@platform@.Templates": { "kind": "template", "version": "@Version@" } These are a starting point, for what I would consider the minimum for the xamarin-macios repo to provide for now: Template Name Short Name Language Tags -------------------------------------------- -------------- ---------- ---------------------- iOS Controller template ios-controller [C#] iOS iOS Application ios [C#] iOS iOS Class library ioslib [C#] iOS macOS Application macos [C#] macOS MacCatalyst Application maccatalyst [C#] macOS/Catalyst tvOS Application tvos [C#] tvOS We will probably need PM input on what the final templates will be. To use these, you might do: $ mkdir MyApp && cd MyApp $ dotnet new ios $ dotnet new ios-controller --name LoginController --namespace MyApp Co-authored-by: Rolf Bjarne Kvinge <[email protected]>
|
Given we shipped work that implements this spec, I'm going to merge if there isn't any further feedback. |
Add spec for workload manifests, expanding on the concepts from the workload overview.