Skip to content

Commit d7858d8

Browse files
PerkseyPerksey
authored
[3.0] Contributor experience improvements (#2405)
* Contributor experience improvements * Document MSBuild USage
1 parent 8dc7148 commit d7858d8

File tree

11 files changed

+140
-2
lines changed

11 files changed

+140
-2
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -473,6 +473,7 @@ src/**/build/
473473
# Silk.NET Build System
474474
*.gen.sln
475475
*.gen.txt
476+
excluded-platforms.txt
476477

477478
# Silk.NET Website Generation Output
478479
#/docs/

‎.nuke/build.schema.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@
2727
"Clean",
2828
"Compile",
2929
"DeclareApi",
30+
"DisablePlatforms",
31+
"FinishRelease",
3032
"Pack",
3133
"Prerequisites",
3234
"PushToNuGet",
@@ -134,6 +136,10 @@
134136
"Release"
135137
]
136138
},
139+
"DiscordWebhook": {
140+
"type": "string",
141+
"description": "Discord release announcement webhook"
142+
},
137143
"MsbuildProperties": {
138144
"type": "array",
139145
"description": "Extra properties passed to MSBuild commands",
@@ -161,6 +167,13 @@
161167
"type": "string",
162168
"description": "NuGet username"
163169
},
170+
"Platforms": {
171+
"type": "array",
172+
"description": "A list of platforms that DisablePlatforms should exclude from MSBuild usages, both inside and outside of NUKE. This can be reset by running DisablePlatforms with no platforms, or by deleting the excluded-platforms.txt file",
173+
"items": {
174+
"type": "string"
175+
}
176+
},
164177
"SilkTouchAdditionalArgs": {
165178
"type": "array",
166179
"description": "Additional arguments to prepend to SilkTouch invocations",

‎Directory.Build.props

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,4 +77,15 @@
7777
<IncludeSymbols>true</IncludeSymbols>
7878
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
7979
</PropertyGroup>
80+
81+
<PropertyGroup>
82+
<SilkExcludedPlatforms />
83+
<SilkExcludedPlatforms Condition="Exists('$(MSBuildThisFileDirectory)excluded-platforms.txt')">$([System.IO.File]::ReadAllText("$(MSBuildThisFileDirectory)excluded-platforms.txt"))</SilkExcludedPlatforms>
84+
<SilkExcludedPlatforms Condition="$([MSBuild]::IsOSPlatform('Linux'))">$(SilkExcludedPlatforms) ios tvos mac maccatalyst</SilkExcludedPlatforms>
85+
<SilkAndroidDisabled Condition="$(SilkExcludedPlatforms.Contains('android'))">true</SilkAndroidDisabled>
86+
<SilkiOSDisabled Condition="$(SilkExcludedPlatforms.Contains('ios'))">true</SilkiOSDisabled>
87+
<SilkTvOSDisabled Condition="$(SilkExcludedPlatforms.Contains('tvos'))">true</SilkTvOSDisabled>
88+
<SilkMacDisabled Condition="$(SilkExcludedPlatforms.Contains('mac'))">true</SilkMacDisabled>
89+
<SilkMacCatalystDisabled Condition="$(SilkExcludedPlatforms.Contains('maccatalyst'))">true</SilkMacCatalystDisabled>
90+
</PropertyGroup>
8091
</Project>

‎Directory.Build.targets

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@
201201
<Error Text="Native packages should have a version.txt file! Read documentation/for-contributors/build-system.md for more info."
202202
Condition="'$(SilkNativePackage)' == 'true' and !Exists('$(SilkVersionTxtPath)')" />
203203
<ItemGroup Condition="'$(SilkNativePackage)' == 'true'">
204-
<None Include="$(MSBuildProjectDirectory)/runtimes/**/*" Pack="true" PackagePath="runtimes" />
204+
<None Include="$(MSBuildProjectDirectory)/runtimes/**/*" Pack="true" PackagePath="runtimes" KeepMetadata="Link;CopyToOutputDirectory" CopyToOutputDirectory="PreserveNewest" />
205205
<!-- bundled in the aar instead -->
206206
<None Remove="$(MSBuildProjectDirectory)/runtimes/android*/**/*" Condition="'$(SilkNativeHasAndroidJars)' == 'true'" />
207207
</ItemGroup>
@@ -260,4 +260,14 @@
260260
Condition="'$(IncludeBuildOutput)' == 'false'" />
261261
</ItemGroup>
262262
</Target>
263+
264+
<!-- This is a bodge to make native packages feel like they're working when in repo i.e. with ProjectReferences -->
265+
<Target Name="SilkProjectReferenceNatives" AfterTargets="GetCopyToOutputDirectoryItems" Condition="'$(RuntimeIdentifier)' != ''">
266+
<ItemGroup>
267+
<SilkThisRidItems Include="@(AllItemsFullPathWithTargetPath)"
268+
Condition="$([System.String]::Copy('%(TargetPath)').Contains('$(RuntimeIdentifier)')) or $([System.String]::Copy('%(TargetPath)').Contains('$(RuntimeIdentifier.Split('-')[0])'))"
269+
TargetPath="$([System.String]::Copy('%(Filename)%(Extension)'))" />
270+
</ItemGroup>
271+
<Copy SourceFiles="@(SilkThisRidItems)" DestinationFiles="@(SilkThisRidItems->'$(OutDir)%(TargetPath)')" />
272+
</Target>
263273
</Project>

‎docs/for-contributors/README.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# The Silk.NET Contributors Guide
2+
3+
Welcome to the Silk.NET project! We're so glad you want to help us create the best native interoperation experience that
4+
.NET has ever seen.
5+
6+
This contributors guide covers many topics about Silk.NET's internals in great detail to help anyone pick up any part of
7+
the codebase and hit the ground running.
8+
9+
## Table of Contents
10+
11+
- [Getting Started (you are here!)](#getting-started)
12+
- [Build System](build-system.md)
13+
14+
15+
## Getting Started
16+
17+
### Prerequisites
18+
19+
To get started, first clone Silk.NET using `git clone https://github.com/dotnet/Silk.NET --depth 1`. Your development
20+
environment will need the latest production-ready .NET SDK, so make sure you've installed that from
21+
[get.dot.net](https://get.dot.net). We also recommend installing NUKE using `dotnet tool install -g NUKE.GlobalTool` to
22+
enable our auxiliary build commands/utilities, but this is optional and in fact can be accessed using the
23+
`./build.sh`/`.\build.cmd`/`.\build.ps1` scripts in place of `nuke` in usages in this guide without installing the tool.
24+
25+
If you'd like to build and/or work with the mobile support in Silk.NET, you'll need to install the workloads using
26+
`dotnet workload restore`. It is highly likely you need to prefix this with `sudo` on macOS and Linux. In addition,
27+
you'll need to install the Android SDK with API 34 and API 35 support to ensure a successful build. Furthermore, on
28+
macOS you will need Xcode installed with the iOS platform installed. Alternatively, if you don't want to work with our
29+
mobile support, you can disable it for your local builds using `nuke disable-platforms --platforms android ios` for
30+
example. The acceptable values for `--platforms` are any valid platform identifiers (i.e. right-hand side of the `-` of
31+
a `TargetFramework`, without platform version information).
32+
33+
We automatically disable iOS support on Linux, as these workloads are only available on Windows and macOS. For more
34+
information about the NUKE utilities, consult the [Build System](build-system.md) documentation or use `nuke --help`.
35+
36+
### Building from Source
37+
38+
Assuming you've got the prerequisites installed, `dotnet build`! Or `dotnet pack` to produce all the NuPkgs in
39+
`artifacts/pkg`.
40+
41+
To learn more about the build system, see the [Build System](build-system.md) documentation. It is intentionally
42+
designed to be as compatible as possible with the regular `dotnet build` system such that you can use the built-in
43+
utilities of your favourite IDE.
44+
45+
### Regenerating Bindings
46+
47+
You can regenerate bindings using NUKE with `nuke regenerate-bindings`, but this isn't recommended. A full regeneration
48+
of Silk.NET takes a long time and has the potential to touch the vast majority of the files that make up Silk.NET and/or
49+
create loads of unrelated changes in your working tree. Instead, it is preferred to run SilkTouch manually using a
50+
command like
51+
`dotnet run --project sources/SilkTouch/SilkTouch/Silk.NET.SilkTouch.csproj -c Release -- generator.json -s Job1 -s Job2 ...`
52+
where the values for the `-s` arguments are replaced with the job names (the keys of the `Jobs` dictionary in
53+
`generator.json` e.g. `SDL`, `OpenGL`, etc).
54+
55+
For more information on SilkTocuh arguments, consult the [SilkTouch User Guide](../silktouch) or use
56+
`dotnet run --project sources/SilkTouch/SilkTouch/Silk.NET.SilkTouch.csproj -- --help`.
57+

‎docs/for-contributors/build-system.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@ library itself that are provided by a auxiliary build system implemented using t
66

77
## MSBuild Usage
88

9+
### Target Frameworks
10+
11+
It is our goal to always target the latest LTS .NET release, and optionally multi-targeting to the next non-LTS version
12+
thereafter. We also make use of the mobile frameworks e.g. `net8.0-android`, `net8.0-ios`, but these shall always be
13+
guarded using properties such as `SilkAndroidDisabled`, `SilkiOSDisabled` etc which are set in `Directory.Build.props`,
14+
which in turn check whether a file named `excluded-platforms.txt` exists and contains the target platform identifier.
15+
This can be quickly modified by using the NUKE target `nuke disable-platforms`, which just writes to this file the
16+
values provided for `--platforms`.
17+
918
### Package READMEs
1019

1120
NuGet has recently added functionality to include a "README" rendered from Markdown on the front page of a package in
@@ -160,6 +169,21 @@ automatically, however in some cases there are specific linker flags required wh
160169
The `.targets` injected can be seen at `eng/native/nuget/NativeNuGetPackage.targets` with the `TO_BE_REPLACED`
161170
placeholders replaced in `Directory.Build.targets`.
162171

172+
Obviously, the native packages only work when consumed as a NuGet. However, we have a "best effort" attempt to copy the
173+
appropriate native binary to the output directory for projects that `ProjectReference` a native binary, whether directly
174+
or transitively. To make this work however, projects must include this:
175+
```xml
176+
<Project>
177+
<PropertyGroup>
178+
<RuntimeIdentifier Condition="'$(RuntimeIdentifier)' == ''">$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
179+
</PropertyGroup>
180+
</Project>
181+
```
182+
183+
This logic is defined in the `SilkProjectReferenceNatives` target in `Directory.Build.targets`.
184+
185+
We currently have not explored doing this for static linking (i.e. iOS) builds.
186+
163187
## Native Build Workflow
164188

165189
As mentioned previously, we build all of our native binaries in CI to ensure they come from a trusted source and also to

‎eng/build/Build.cs

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
using Nuke.Common;
33
using Nuke.Common.IO;
44
using Nuke.Common.Tools.DotNet;
5+
using Nuke.Common.Utilities;
56
using static Nuke.Common.Tools.DotNet.DotNetTasks;
67

78
partial class Build : NukeBuild
@@ -112,4 +113,22 @@ out var releaseNotes
112113
await SendWebhookAsync(version, versionSuffix, releaseNotes);
113114
})
114115
);
116+
117+
[Parameter(
118+
$"A list of platforms that {nameof(DisablePlatforms)} should exclude from MSBuild usages, both "
119+
+ $"inside and outside of NUKE. This can be reset by running {nameof(DisablePlatforms)} with no platforms, "
120+
+ $"or by deleting the excluded-platforms.txt file."
121+
)]
122+
readonly string[]? Platforms;
123+
124+
Target DisablePlatforms =>
125+
CommonTarget(x =>
126+
x.Executes(
127+
() =>
128+
File.WriteAllText(
129+
RootDirectory / "excluded-platforms.txt",
130+
(Platforms ?? []).Join(' ')
131+
)
132+
)
133+
);
115134
}

‎sources/Playground/Playground.csproj

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<TargetFramework>net8.0</TargetFramework>
66
<ImplicitUsings>enable</ImplicitUsings>
77
<Nullable>enable</Nullable>
8+
<RuntimeIdentifier Condition="'$(RuntimeIdentifier)' == ''">$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
89
</PropertyGroup>
910

1011
<ItemGroup>

‎sources/Playground/libSDL3.dylib

-1.93 MB
Binary file not shown.

‎sources/SDL/Native/Silk.NET.SDL.Native.csproj

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
<Project Sdk="Microsoft.NET.Sdk">
22

33
<PropertyGroup>
4-
<TargetFrameworks>net8.0;net8.0-android</TargetFrameworks>
4+
<TargetFrameworks>net8.0</TargetFrameworks>
5+
<TargetFrameworks Condition="'$(SilkAndroidDisabled)' != 'true'">$(TargetFrameworks);net8.0-android</TargetFrameworks>
56
<SilkDescription>Native binaries for SDL3.</SilkDescription>
67
<SilkNativePackage>true</SilkNativePackage>
78
<SilkNativeHasAndroidJars>true</SilkNativeHasAndroidJars>

0 commit comments

Comments
 (0)