Skip to content

Commit 5df7424

Browse files
dseefelddseefeld
authored
Merge pull request #2103 from omajid/patch-new-rid-doc
Add a doc describing how to add new RIDs to source-build
2 parents a002cbf + 48fc718 commit 5df7424

File tree

2 files changed

+149
-0
lines changed

2 files changed

+149
-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: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
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 of dotnet/runtime or dotnet/corefx
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 change 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 dotnet/runtime or dotnet/corefx with the
112+
`/p:UpdateRuntimeFiles=true` flag:
113+
114+
```
115+
./build.sh /p:UpdateRuntimeFiles=true
116+
```
117+
118+
Building should result in a patch that updates
119+
`runtimeGroups.props`, but also `runtime.json` and
120+
`runtime.compatiblity.json`.
121+
122+
3. Commit the results and generate a patch:
123+
124+
```
125+
git commit -a ...
126+
git format-patch -1 HEAD
127+
```
128+
129+
Here's an [example
130+
result](https://src.fedoraproject.org/rpms/dotnet3.1/raw/43e957aabcbcef730c9433b817be947a7820ae67/f/corefx-43032-fedora-35-rid.patch)
131+
of a real patch generated though this approach.
132+
133+
You might also want to create a PR to get this change included into
134+
the main .NET repositories. That will save you the trouble of
135+
having to update this patch yourself in the future.
136+
137+
4. Add that patch to source-build
138+
139+
For .NET Core 3.1 or earlier, add the patch to `patches/corefx/`
140+
141+
For .NET 5, add the patch to `patches/runtime/`
142+
143+
5. Build source-build
144+
145+
Use your regular build steps, such as `./build.sh`. source-build
146+
will apply the new patch and build a new SDK with the new RID
147+
added.

0 commit comments

Comments
 (0)