Repository navigation
Description
RID Plan
We worked on a plan to tame the RID graph last year. It got close to resolution, but not quite far enough. We also didn't have time to fund it as part of .NET 7. We started talking about it again earlier this year. We have defined targeted updates to the earlier plan that we think will get across the finish line.
The goal remains the same, which is to stop updating the RID graph and to stop reading it in all scenarios, by default. Eventually, we want to delete it. The RID graph represents a poor design point of the product, particularly in terms of how it supports Linux, aiming to act as a persisted database of historical and current operating system releases. We're also not doing a great job of keeping it updated to satisfy its intended function.
Quick context
The RID graph is used to two primary spots:
- By
dotnet buildordotnet publishto select the best-match RID-specific assets (primarily from NuGet packages) to generate a RID-specific app. - By the host to select RID-specific assets from a portable app layout.
Put another way, given RID-specific assets in an app NuGet graph, those assets are either selected during build or deferred to runtime.
In both cases, the target RID of the app or the environment often doesn't match the RID of the assets. That's intentional and fine, however resolving that difference requires a best-match algorithm. Today, the RID graph serves as an authoritative database for that algorithm to use.
For example, a portable app might be running on a Linux Mint 19 machine, yet carry assets (for a given dependency) that separately target Ubuntu 18.04 and portable Linux. The host knows (via the RID graph) that the Ubuntu 18.04 asset is compatible with Linux Mint 19 and a better match than the portable Linux asset. It chooses the Ubuntu 18.04 asset.
Open issues
The following issues are the primary ones blocking progress:
- We planned to have an algorithmic approach. Should it include concrete RIDs, like
ubuntu.22.04? - Source build users tend to include concrete RIDs, like
rhel.8. Should we ensure that distro-specifc source-build builds and the portable Linux build have parity in that respect? - How do we handle compatible distros, like Oracle Linux and RHEL or Linux Mint and Ubuntu?
- Can we use the same solution for the apphost and the SDK?
Probing Algorithm
The original plan proposed the following probing model for the portable build:
linux-x64unix
Note: Architecture-specific RIDs are intended for native and ready-to-run code. Architecture-agnostic RIDs are intended for IL code (often related to P/Invokes).
That's probably artificially limited. Source-build users offer a more expansive set of RIDs to probe, which might bias to too much.
We concluded that the following model should satisfy the vast majority of needs.
ubuntu.22.04-x64ubuntu.22.04linux-x64unix
This model would offer symmetry (or symmetry enough) between the portable build and the typical distro-specific source-build build.
Distro compatibility
Expressing distro-compatibility adds a lot of nodes to the centrally-managed RID graph. We also expect that they don't benefit a lot of users. Instead, we propose to move to a model where compatibility relationships are described in app project files for the relatively few apps that need them. We propose roughly similar support as what source-build users have for adding RID information.
We don't want to invent a new format. We have three formats already:
We propose to use the runtime.compatibility.json format, like the following real example:
"linuxmint.19": [
"linuxmint.19",
"ubuntu.18.04",
"ubuntu",
"debian",
"linux",
"unix",
"any",
"base"
]This compatibility description is notable since it doesn't include architecture information. Given a desire for apps to run on multiple architectures, we can algorithmically add architecture when apps (or tools) are running (in a given environment).
We'd recommend a more terse description (to describe just the compatability relationship):
"linuxmint.19": [
"linuxmint.19",
"ubuntu.18.04",
]Multiple compatibility relationships can be described.
{
"linuxmint.19": [
"linuxmint.19",
"ubuntu.18.04",
],
"ol.8": [
"ol.8",
"rhel.8",
],
}We propose that this compatibility information be included in app project files in some new property, like the following:
<PropertyGroup>
<RuntimeCompatibility>
{
"linuxmint.19": [
"linuxmint.19",
"ubuntu.18.04",
],
"ol.8": [
"ol.8",
"rhel.8",
],
}
</RuntimeCompatibility>
</PropertyGroup>The following is an alternative format we will consider:
<ItemGroup>
<RuntimeCompatibility Include="linuxmint.19.2" Fallbacks="linuxmint.19.1;linuxmint.19;ubuntu.18.04;ubuntu;debian" />
<RuntimeCompatibility Include="ol.8" Fallbacks="rhel.8" />
</ItemGroup>This information would be copied into app.deps.json in a new section.
Embedded JSON is a bit ugly. We could use XML, in the runtimeGroups.props format. That would be workable. We'd need to productize the task that converts that XML to JSON. Given how targeted we think the scenario is, we are proposing the simpler JSON-based approach.
The RID graph includes multiple variations for each distro, like ol.8 and ol.8.0. For Linux Mint, there is linuxmint.19.0, linuxmint.19.1, and linuxmint.19.2. For Ubuntu, there is ubuntu.18.04 and ubuntu.18.10. Note the relationships between Linux Mint and Ubuntu releases.
We should reason about distro versions in terms of VERSION_ID in /etc/os-release and then rely on stated compatibility relationships for any differences, including between Linux Mint dot versions (for example).
$ docker run --rm linuxmintd/mint21-amd64 cat /etc/os-release | grep VERSION
VERSION="21 (Vanessa)"
VERSION_ID="21"
VERSION_CODENAME=vanessa
$ docker run --rm linuxmintd/mint21.1-amd64 cat /etc/os-release | grep VERSION
VERSION="21.1 (Vera)"
VERSION_ID="21.1"
VERSION_CODENAME=veraThis means that linuxmint.21 and linuxmint.21.1 would be valid RIDs, but linuxmint.21.0 would not. A compatibility relationship would need to be specified (as described above) to enable an app running on Linux Mint 21.1 to use a linuxmint.21 asset.
The following examples demonstrate the differing compatibility relationships offered by Linux Mint and Ubuntu.
Linux Mint 19.2:
"linuxmint.19.2": [
"linuxmint.19.2",
"linuxmint.19.1",
"linuxmint.19",
"ubuntu.18.04",
"ubuntu",
"debian",
"linux",
"unix",
"any",
"base"
],Ubuntu 18.10:
"ubuntu.18.10": [
"ubuntu.18.10",
"ubuntu",
"debian",
"linux",
"unix",
"any",
"base"
],They key point being made is that there is no compatibility relationship offered between Ubuntu releases. Ubuntu 18.04 assets are not using when running on Ubuntu 18.10. However, both Linux Mint and Ubuntu RIDs offer compatibility to Debian. We will not offer compatibility for any unversioned distro RIDs, like ubuntu and debian.
Note: This doc uses a mix of Linux Mint 19 and 21 since v19.x is the most recent version recorded in the RID graph, while v21.x is the latest stable version. That alone provides evidence of the operational drawbacks of the current model and a benefit that the proposed system would deliver.
Backwards compatibility
The transition to an algorithmic approach to RIDs is a significant change. We will need a backwards compatibility mode.
We propose:
- The apphost uses the algorthmic mode by default.
- There is a property that enables using the existing RID graph approach instead.
- App developers can specify distro compatibility relationships that they want to use.
The expectation is that this combination of modes will enable us to freeze or significantly freeze the RID graph. Assuming we freeze the RID graph, there may be scenarios where users might need to use option #3 in combination with either option 1 or 2.
SDK experience
We need to work through the SDK/tools experience a bit more.
We need an experience that notifies developers that they will not be well-served by the pure algorthmic mode. This will be the case when dotnet restore detects a non-portable RID-specific asset.
Portable RIDs:
linuxunixwinosxwasm
Non-portable RID examples:
linuxmint.19.2ubuntu.18.04rhel.8
If a non-portable RID is discovered in the package graph, the SDK should produce a warning, similar to the following:
"Distribution-specific assets were identified in one or more package references. You may want to add distribution-compatibility relationships to your project file. See http://aka.ms/dotnet/rid/compatibility to learn more."
We would offer some pragma disable option to quiet the warning.
For portable apps, this warning would give developers an opportunity to define compatibility relationships so that the correct assets get used on Linux Mint and Ubuntu, for example.
RID-specific apps are in some ways the easier case. The developer will specify a specific RID and there is an opportunity for the developer to inspect the results and for the SDK to present an error (if there was no best-match asset).
We have a couple options on identifiying non-portable RIDs. We can the discrete list above, or we can rely on the existing RID graph to determine what the non-portable RIDs are. Both are non-perfect.
Regression or improvement?
This proposal is simultaneously a regression and an improvement.
How it is a regression:
- Distro compatibility relationships become an app dev concern.
- .NET doesn't come with distro relationship information, and there is no central place for recording that.
How it is an improvement:
- Distro compatibility relationships can be specified at the point of need.
- RID graph updates are not necessary and no longer need to rely on the expensive and lengthy .NET servicing process.
- The RID graph is inconsistent in its updates. It is now as up to date as needed by the app developer.
A related problem is that we've never provided a way to correctly build portable linux assets. From that point-of-view, it is safer to build distro-specific assets due to that, at least currently. We are considering offering guidance on how to build linux assets. We're hoping that encourages producing more portable assets where there might be distro-specific ones today.
Impact on Source-Build
Today, source-build users rely on augmenting the RID graph via MSBuild. Assuming we can lock the RID graph, that will no longer make much sense. Instead, we'd need to move source-build users to this plan. That will likely mean making changes in host code instead of to the RID graph.
Deletion of RID graph
We should delete the RID graph with the .NET 9 or 10 releases, ideally the earlier of the two. The .NET 8 release should give us insight into which scenarios have a strong dependency on this data.
Activity
agocke commentedon Mar 10, 2023
Unfortunately, I think this is still too complicated and provides support for scenarios that we should drop entirely.
As mentioned in above, I believe that RIDs serve two purposes:
By encoding a very complex description of "platform" in RIDs, it's allowed NuGet packages and the runtime a very large amount of flexibility in micro-targeting exactly which assets to provide different platforms.
I think this flexibility was a mistake. The vast majority of NuGet packages do not make use of this flexibility, and in fact, for many of them, attempting to target many OS variants has proven to be a headache rather than a boon.
Instead, I think RIDs should express a basic, widely used definition of "binary compatibility." Most commonly this refers to "ABI", or C-language compatibility. By using this definition we would not make it possible to deliver arbitrary assets for arbitrary operating systems, but we would allow apps and libraries to provide assets which can communicate over the generally understood C ABI for that system.
Practically, this would shrink the RID system to exactly these components:
This system would imply that you would not be able to deliver app dependencies that have a stronger-than-C-ABI requirement using the .NET tooling. I believe this is a viable and preferrable system. For operating systems like Windows and Mac, this is rarely a problem as there are few variations and the C-ABI is the dominant interop system.
For Linux distributions, many libraries and apps would not find this particularly constraining, as many of them want to provide maximal portability regardless. For others, which would like to do more specific distro targeting, historically Linux distributions have provided system package managers for exactly this reason.
Our new recommendations would be:
agocke commentedon Mar 10, 2023
richlander commentedon Mar 10, 2023
I hear you saying that you liked the original proposal better, which focused on the Linux portable RID and not specific distros like Ubuntu 22.04 let alone its relationship with Linux Mint.
We started this expanded proposal since developers on our team publish distro-specific RID-split packages.
I feel like you are missing the key point that this proposal agrees with your feedback. It is intended to significantly curtail the descriptive capability that we provide by default. It also enables a compatible bridge to a simpler system.
I see you saying that you are willing to accept the break that your proposal entails. I agree that distro specific packages are not common however I don't see tour proposed break as necessary to get us on a better path.
@tannergooding
agocke commentedon Mar 10, 2023
That's a fair critique. My understanding is that this system still defines a public API which has to be understood by NuGet authors and distro maintainers. I am worried that even having these capabilities available substantially complexifies the ecosystem. Is there something I'm overlooking?
richlander commentedon Mar 10, 2023
Can you define the public API you see?
agocke commentedon Mar 10, 2023
I see this as moving from an explicit contact to an implicit contract. In the package side, it would be the responsibility of package authors to survey the space of distros and provide specific assets. On the distro side, they would be pressured to provide unique identifiable info in /etc/os-release.
In the best case, it seems like there would be significant package churn as distros lobby various packages to add them to the list. Or, distros won't lobby at all and users of those distros will be stuck without binaries.
In the worst case, it seems like this could end up like user-agent, with everyone lying about their name and the packages looking for the right lies.
On the other hand, if we don't have a system like this at all, packages will be pressured to either find some way to provide true portable binaries for maximum compat with no configuration, or level the distro playing field by moving the whole system to external package managers.
vitek-karas commentedon Mar 10, 2023
This assumes that .NET will be a driving force to change what distros return in their
/etc/os-release. I'd love to think .NET will be that popular, but I highly doubt it. I think it's safer to assume that basically nobody in the .NET ecosystem will have any say to what is returned there -> expect the unexpected/chaos.I like this idea. Personally I would go with the MSBuild native syntax - embedding JSON into msbuild looks really weird. And embedding XML will make things probably even worse. (Note: The current json format is mostly invisible to developers, with the exception of distro authors, so I think there's little value in trying to reuse it)
One additional consideration - if I'm shipping a NuGet which has distro specific assets I might want to augment the RID graph in every app the NuGet is referenced. This is obviously doable as NuGets can inject targets into the msbuild, but I think we should consider this as another aspect of the solution. (And yes, this comes with the danger that someone will publish a NuGet which adds back the entire RID graph as we know it today... I don't know how I feel about it... but we won't do that ourselves).
I think that is sort of orthogonal - the above proposal doesn't make it any easier to maintain distro specific packages, it probably makes it actually harder. So the incentive is there already. It's just not a "you must migrate" statement. I also think that we can't try to force packages to distro agnostic unless we have a good solution how to produce such packages (like the manylinux target and docker images to use to build assets on). On that topic - are we even the right group to try to do that? Why not piggy back on some other platform which already solves this to some extent (like Python). We're bound to create something sufficiently different that it won't make this easier for developers necessarily.
tmds commentedon Mar 10, 2023
I would add
ubuntu.22-x64,ubuntu.22to this. It doesn't mean anything for Ubuntu, but for distros that have a<major>.<minor>scheme where themajorindicates binary compatibility (like RHEL) it makes things work.+1 for going from rid graph model to rid compatibility model.
That is a lot less to express.
It would be nice if this compatibility could be expressed in a NuGet package, and Microsoft would still maintain such a package.
Dealing with the compatibility relationships should be a matter of referencing this package, unless there are rids involved not yet known by the package.
As @vitek-karas suggested, the package maintainer can include this information for the non-portable rids he includes.
He could do so by referencing the compatibility package, if that includes these non-portable rids already.
For the published app, the compatibility information can be trimmed down based on the non-portable rids for which there are actual artifacts (include those, and their derivative distros).
janvorli commentedon Mar 10, 2023
In the portable list above, I don't see linux-musl / linux (with glibc) distinction. Is that intentional? Executable assets like shared libraries are not compatible between those two, so it seems we will need both.
agocke commentedon Mar 10, 2023
@janvorli I believe in this proposal all the "portable" rids would stick around, so
linux-musl-x64would still be there.elinor-fung commentedon Mar 10, 2023
Yeah, portable would still have linux-musl vs. linux.
Definitely a good consideration. This would lean towards the MSBuild-y syntax too.
As in you think that should be part of the algorithmic model? Since we're trying to get out of .NET knowing/maintaining compatibility relationships, I'd see that as something that can be specified by the app via the proposed distro compatibility mechanism.
57 remaining items
tmds commentedon Apr 7, 2023
Yes. We've challenged a couple of times the need to automatically pick up non-portable assets at runtime.
The only thing said about that (in #83246 (comment)) is:
agocke commentedon Apr 10, 2023
Seems like it would be pretty powerful and useful. Two questions:
elinor-fung commentedon Apr 11, 2023
I would be concerned that not probing the current RID would turn this into significantly more of a breaking change for non-linux, particularly Windows. I know there are a lot of packages that have win10 assets (maybe some of them aren't actually win10 specific, but I did see some high downloads that were intended to only support win10).
As various folks have mentioned before, some packages do already use
NativeLibrary,DllImportResolver,ResolvingUnmanagedDll, and friends to do their own resolution. I know there was pushback from package owners around the complexity, hence the proposal for a declarative system. If the declarative system still seems to be a partial solution, maybe we just commit to the stronger break, create guidance/examples, and push of the complexity to code in packages that would be affected. From what data I was able to query on public nuget, I found ~700 packages that assets under runtimes/.I think I'm missing the scenario here. Is this for using a source-built SDK to build/publish a RID-specific application that uses distro-specific assets that aren't an exact match to the RID specified on build/publish?
agocke commentedon Apr 11, 2023
That was my thought, yeah. I'm the maintainer for BananaLinux and I make source-build copy of .NET. I want to express compatibility for all Ubuntu packages >= 16.04 and <= 22.04, and all minor versions of CarrotLinux 4.x.
tmds commentedon Apr 13, 2023
My understanding is that, under this proposal, the compatibility information is no longer the responsibility of the .NET installation.
The app developer is responsible for including it (when their app comes with non-portable assets).
This works the same for Microsoft built .NET and source-built .NET.
agocke commentedon Apr 15, 2023
That makes more sense -- so this would go in the user's app and they would use this resolution policy there.
elinor-fung commentedon May 8, 2023
Based on the suggestion (re)raised in #83246 (comment) around not trying to add a declarative system:
NativeLibrary.SetDllImportResolverorAssemblyLoadContext.ResolvingUnmanagedDllfor custom loading logicThis is basically the last plan, without the declarative system (so 'opt-in: distro compatibility' and ‘major <- major.minor’ removed).
We looked at the data available to us for packages listed on NuGet. Based on paths of items in the package, we identified ~700 distinct packages out of 490k packages that had non-portable RID assets in any of their versions. Only 250 of those used linux RIDs (most were windows). A number of the commonly downloaded ones (for example, Libuv, SkiaSharp and LibGit2Sharp) no longer had non-portable RID assets in their latest versions.
This seems to support the position of avoiding the complexity of adding a declarative system and pushing it to applications/libraries to add a custom mechanism using existing APIs.
tmds commentedon May 8, 2023
Is this right: the algoritmic probing doesn't probe for any non-portable rids (for portable builds)?
I think the algorithimc probing is good if it:
elinor-fung commentedon May 8, 2023
I think it should still probe for the RID of the host itself - so the fallback RID passed at build-time (with the same version stripping or not as in the build scripts), which I believe would include the non-portable RID for non-portable builds of the host.
tmds commentedon May 8, 2023
My question is about the algorithmic model at runtime: whether it adds a non-portable rid based on the
/etc/os-releasefrom the host it is running on, or whether the list is fixed as build time?From your reply, I assume it's the latter? And this fixed list could include a non-portable rid.
elinor-fung commentedon May 8, 2023
Yes, I was thinking it would be the fixed list from build time. I'm hoping that would help move us away from the (often confusing) determination at run time. Happy to hear any other opinions though.
ericstj commentedon Oct 24, 2023
@richlander - are you using this issue to track any more remaining work in 8.0 or can it be closed/milestone updated?
richlander commentedon Oct 24, 2023
This was implemented in .NET 8, so closing.