Skip to content

Commit 5a1253a

Browse files
omajidomajid
committed
Add a doc describing how to add new RIDs to source-build
Anyone else adding their Linux distribution's RID to source-build might find this useful. I am trying to get this out of my head and into a shape where others can make use of this. See: #2095
1 parent c13177f commit 5a1253a

File tree

2 files changed

+148
-0
lines changed

2 files changed

+148
-0
lines changed

‎Documentation/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ artifacts/${ARCHITECTURE}/Release/dotnet-sdk-${SDK_VERSION}-${RUNTIME_ID}.tar.gz
3434

3535
For example, building a 3.1.105 SDK on an x64 (aka x86\_64) platform running Fedora 32 will produce `artifacts/x64/Release/dotnet-sdk-3.1.105-fedora.32-x64.tar.gz`.
3636

37+
If you run into an error about an unknown `RuntimeIdentifier`, see [Adding a new Runtime Identifier to source-build](add-new-rid.md).
38+
3739
If you are interested in "installing" this SDK system wide or making a Linux package out of the SDK, please see [Packaging and Installation](packaging-installation.md).
3840

3941
`./build.{cmd|sh}` accepts a number of parameters to control the build.

‎Documentation/add-new-rid.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Adding a new Runtime Identifier (RID) to source-build
2+
3+
This document describes how to add a new Runtime Identifier (also
4+
called runtime id or even just RID) to source-build. You might find
5+
this useful if you see an error like this when building source-build:
6+
7+
```
8+
error NETSDK1083: The specified RuntimeIdentifier 'foo.bar-x64' is not recognized.
9+
```
10+
11+
# Assumptions
12+
13+
- .NET (coreclr, source-build, etc) already supports this new OS.
14+
15+
For example, this could be a new version of a Linux distribution
16+
that's already known to work. Or it could be a fork of another Linux
17+
distribution which is expected to work
18+
19+
- source-build computes the RID correctly
20+
21+
Source-build computes the RID, at least on Linux, by looking at
22+
`/etc/os-release` and running `${VERSION}.${VERSION_ID}-$(uname
23+
-m)`. If the result of this computation itself is wrong (for example
24+
a rolling Linux distro doesn't use `VERSION_ID`), the steps in this
25+
doc wont be sufficient.
26+
27+
- We just need to add things to the RID graph
28+
29+
This isn't a brand new platform, just a slight tweak to an existing
30+
one.
31+
32+
# Step-by-step fix
33+
34+
This error message is generally from the rolysn build:
35+
36+
```
37+
error NETSDK1083: The specified RuntimeIdentifier 'foo.bar-x64' is not recognized.
38+
```
39+
40+
It means that the SDK that's being used to build roslyn doesn't have
41+
the RID in it's RID graph. We can fix that.
42+
43+
The RID is generally present in 2 places:
44+
45+
1. `RuntimeIdentifierGraph.json` in a built-SDK
46+
47+
2. `Microsoft.NETCore.Platforms/runtime.json` in the source
48+
repositories (dotnet/runtime or dotnet/corefx)
49+
50+
Generally fixing the second one is sufficient.
51+
52+
Here's how to fix it.
53+
54+
1. Grab the source code
55+
56+
For .NET Core (3.1 or earlier):
57+
58+
```
59+
git clone https://github.com/dotnet/corefx
60+
cd corefx
61+
git checkout release/$version
62+
```
63+
64+
For .NET (5 or later):
65+
66+
67+
```
68+
git clone https://github.com/dotnet/runtime
69+
cd runtime
70+
git checkout release/$version
71+
```
72+
73+
2. Add your new RID to `Microsoft.NETCore.Platforms`'s
74+
`runtimeGroups.props` file
75+
76+
If you are adding a new Linux distro, the chagne might look
77+
something like this:
78+
79+
```diff
80+
--- a/pkg/Microsoft.NETCore.Platforms/runtimeGroups.props
81+
+++ b/pkg/Microsoft.NETCore.Platforms/runtimeGroups.props
82+
@@ -40,6 +40,11 @@
83+
<TreatVersionsAsCompatible>false</TreatVersionsAsCompatible>
84+
</RuntimeGroup>
85+
86+
+ <RuntimeGroup Include="exherbo">
87+
+ <Parent>linux</Parent>
88+
+ <Architectures>x64</Architectures>
89+
+ </RuntimeGroup>
90+
+
91+
<RuntimeGroup Include="fedora">
92+
<Parent>linux</Parent>
93+
<Architectures>x64;arm64</Architectures>
94+
```
95+
96+
If you are just adding a new version, it might look like this:
97+
98+
```diff
99+
--- a/pkg/Microsoft.NETCore.Platforms/runtimeGroups.props
100+
+++ b/pkg/Microsoft.NETCore.Platforms/runtimeGroups.props
101+
@@ -43,7 +43,7 @@
102+
<RuntimeGroup Include="fedora">
103+
<Parent>linux</Parent>
104+
<Architectures>x64;arm64</Architectures>
105+
- <Versions>23;24;25;26;27;28;29;30;31;32;33;34</Versions>
106+
+ <Versions>23;24;25;26;27;28;29;30;31;32;33;34;35</Versions>
107+
<TreatVersionsAsCompatible>false</TreatVersionsAsCompatible>
108+
</RuntimeGroup>
109+
```
110+
111+
Then build with the `/p:UpdateRuntimeFiles=true` flag:
112+
113+
```
114+
./build.sh /p:UpdateRuntimeFiles=true
115+
```
116+
117+
Building should result in a patch that updates
118+
`runtimeGroups.props`, but also `runtime.json` and
119+
`runtime.compatiblity.json`.
120+
121+
3. Commit the results and generate a patch:
122+
123+
```
124+
git commit -a ...
125+
git format-patch -1 HEAD
126+
```
127+
128+
Here's an [example
129+
result](https://src.fedoraproject.org/rpms/dotnet3.1/raw/43e957aabcbcef730c9433b817be947a7820ae67/f/corefx-43032-fedora-35-rid.patch)
130+
of a real patch generated though this approach.
131+
132+
You might also want to create a PR to get this change included into
133+
the main .NET repositories. That will save you the trouble of
134+
having to update this patch yourself in the future.
135+
136+
4. Add that patch to source-build
137+
138+
For .NET Core 3.1 or earlier, add the patch to `patches/corefx/`
139+
140+
For .NET 5, add the patch to `patches/runtime/`
141+
142+
5. Build source-build
143+
144+
Use your regular build steps, such as `./build.sh`. source-build
145+
will apply the new patch and build a new SDK with the new RID
146+
added.

0 commit comments

Comments
 (0)