stride3d/stride
1
0
Fork 0
mirror of https://github.com/stride3d/stride.git synced 2026-10-12 02:23:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: move build/docs to docs/build, simplify top-level README

Browse Source 
Move the build-internals docs (SDK-GUIDE.md, plus the new build/README.md
created in this PR) under docs/. Trim the top-level README's prerequisites
to the 3 essentials (Git, .NET 10 SDK, VS 2026 with C++ + .NET workloads)
and link to docs/build/README.md for specifics — toolset versions, optional
ARM64/iOS/Android/VSIX components, Build Tools / dotnet build paths, and
troubleshooting all live there.

Drop the stale C++/CLI workload requirement (no current vcxproj uses
CompileAsManaged). Fix git lfs clone -> git clone (LFS auto-fetches with a
modern git+LFS install).
This commit is contained in:
Virgile Bello
2026-05-09 13:32:56 +09:00
parent 55b468e66a
commit 6ee2e04ce3
11 changed files with 102 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+8 -60
View File
@@ -35,70 +35,18 @@ Our [Roadmap](https://doc.stride3d.net/latest/en/contributors/roadmap.html) comm
### Prerequisites
1. **Latest [Git](https://git-scm.com/downloads)** with **Large File Support** selected during setup. For convenience, you might also use a Git UI client like [GitExtensions](https://gitextensions.github.io/).
2. **[.NET 10.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)**
- Run `dotnet --info` in a console or PowerShell window to see which versions you have installed.
3. **[Visual Studio 2026](https://visualstudio.microsoft.com/downloads/)** (the Community edition is free), with the following workloads. Follow this link if you would rather use [a different IDE or the command line](#build-stride-without-visual-studio).
- **.NET desktop development** with **.NET Framework 4.7.2 targeting pack** *(should be enabled by default)*
- **Desktop development with C++** with:
- **Windows 11 SDK (10.0.22621.0)** or a later version *(should be enabled by default)*
- **MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)** *(should be enabled by default)*
- **MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (Latest)** *(not enabled by default, click Individual components tab to select or search)*
- **C++/CLI support for v143 build tools (Latest)** *(not enabled by default)*
- *Optional* (to target iOS/Android): **.NET Multi-platform App UI development** and the **Android SDK setup** individual component (enabled by default). Then, in Visual Studio, go to `Tools > Android > Android SDK Manager` and install **NDK** (version 20.1+) from the `Tools` tab.
- *Optional* (to build the VSIX package): **Visual Studio extension development**
1. **Latest [Git](https://git-scm.com/downloads)** — the Windows installer includes Git LFS by default; make sure it stays enabled. For convenience, you can also use a UI client like [GitExtensions](https://gitextensions.github.io/).
2. **[Visual Studio 2026](https://visualstudio.microsoft.com/downloads/)** (Community edition is free), with these two workloads:
- **.NET desktop development** (bundles the .NET 10 SDK)
- **Desktop development with C++**
> [!NOTE]
> The installation of Visual Studio with the required components may require up to **19 GB of disk space**, depending on your system and selected components.
> [!WARNING]
> If this is your first time installing the .NET SDK, you might need to restart your system after the installation so that the system can recognize the new environment variables.
> See [docs/build/README.md](docs/build/README.md) for detailed prerequisites (specific MSVC toolset versions, optional iOS/Android/ARM64/VSIX components, command-line builds without VS, and troubleshooting).
### Build Stride
1. **Clone the repository** using a Git UI client or from the command line:
```bash
git clone https://github.com/stride3d/stride.git
```
2. **Open the solution:**
- Open `<StrideDir>\build\Stride.sln` with Visual Studio 2026.
- Build the `Stride.GameStudio` project in the `60-Editor` solution folder (it should be the default startup project) or run it directly from Visual Studio's toolbar.
- _Optionally_, open and build `Stride.Android.sln`, `Stride.iOS.sln`, etc.
> [!WARNING]
> **Do NOT use GitHub -> Code -> Download ZIP** option, as this won't include the LFS files.
### Build Stride without Visual Studio
1. **Install** [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) (Go to *Tools for Visual Studio* and press download next to Build Tools for Visual Studio 2026) with the same prerequisites listed above.
2. **Add MSBuild to your system's PATH:**
- Add MSBuild's directory to your `PATH` environment variable (e.g., `c:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\MSBuild\Current\Bin`).
3. **Clone the repository:**
```bash
git lfs clone https://github.com/stride3d/stride.git
```
4. **Build using the command line:**
- Navigate to the `/build` directory in the command prompt and run:
```bash
msbuild /t:Build Stride.build
```
This restores and builds the full solution.
### If Building Fails
* Some errors for test projects are normal, GameStudio will start anyway.
* The Visual Studio extension might fail to build if you are missing the [Visual Studio SDK](https://learn.microsoft.com/en-us/visualstudio/extensibility/installing-the-visual-studio-sdk?view=vs-2026), but Game Studio will start anyway.
* If you skipped any of the **Prerequisites** thinking you already have the latest version, please update to the latest to be sure.
* Visual Studio might have issues building properly if an older version is present alongside 2026. If you want to keep those versions, ensure they are up to date and that you are building Stride using Visual Studio 2026.
* Your system's `PATH` should not contain older versions of MSBuild (e.g., `...\Microsoft Visual Studio\2019\BuildTools\MSBuild\Current\Bin` should be removed).
* Some changes might require a system reboot. Try that if you haven't yet, for example, if you see these errors:
* `Could not find a compatible version of MSBuild.`
* `Path to dotnet executable is not set.`
* Ensure that Git, Git LFS, and Visual Studio can access the internet.
* Close Visual Studio, clear the NuGet cache (`dotnet nuget locals all --clear`), delete the hidden `.vs` folder inside `\build` and the files inside `bin\packages`, kill any `msbuild` and other Visual Studio processes, then build the whole solution and run GameStudio.
> [!WARNING]
> Test solutions might fail, but this should not prevent you from building `Stride.GameStudio`.
1. `git clone https://github.com/stride3d/stride.git`
2. Open `build\Stride.sln` in Visual Studio 2026.
3. Build the `Stride.GameStudio` project (default startup, in the `60-Editor` folder) or run it directly from the toolbar.
### Contribution Guidelines
docs/build/README.md
Vendored
+77
View File
@@ -0,0 +1,77 @@
# Building Stride from Source — Detailed Guide
This document covers detailed build prerequisites, alternative build paths, and troubleshooting beyond what's in the top-level [README](../../README.md).
## Detailed Prerequisites
### Visual Studio 2026 — Required Components
When installing VS 2026, make sure these are selected:
**.NET desktop development workload** — defaults are sufficient.
**Desktop development with C++ workload** — defaults are sufficient. Specific components used:
- **Windows 11 SDK (10.0.22621.0 or later)** *(default)*
- **MSVC Build Tools for x64/x86 (Latest)** *(default — currently v145.x in VS 2026)*
**Optional components:**
- **MSVC Build Tools for ARM64/ARM64EC (Latest)** — only needed if you actively develop or package for Windows ARM64. If missing, the ARM64 native build is **automatically skipped with a warning** (the rest of the build still succeeds).
- **.NET Multi-platform App UI development** + **Android NDK 20.1+** (via *Tools > Android > Android SDK Manager*) — to target iOS/Android.
- **Visual Studio extension development** + **.NET Framework 4.7.2 targeting pack** — to build the VSIX package.
> [!NOTE]
> Why v145 specifically? Stride pins to v145 to keep release binaries reproducible across contributors and CI. Bumping the pin is roughly a 3-4 year cadence (once per VS major release).
> [!NOTE]
> The Visual Studio install with C++ + .NET workloads typically uses ~19 GB of disk space.
> [!WARNING]
> If this is your first time installing the .NET SDK, you might need to restart so that environment variables are picked up.
## Build With Visual Studio
1. `git clone https://github.com/stride3d/stride.git`
2. Open `build\Stride.sln` in Visual Studio 2026.
3. Build the `Stride.GameStudio` project (default startup, in the `60-Editor` folder) or run it directly from the toolbar.
## Building Without Visual Studio
### Using Build Tools + MSBuild
If you'd rather not install the full Visual Studio IDE:
1. Install the **[.NET 10.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)** (bundled with VS Desktop Development workload, otherwise standalone).
2. Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) (under *Tools for Visual Studio* → Build Tools for Visual Studio 2026), with the same workloads listed above.
3. Add MSBuild to your `PATH` (e.g. `C:\Program Files\Microsoft Visual Studio\18\BuildTools\MSBuild\Current\Bin`).
4. Clone the repo:
```bash
git clone https://github.com/stride3d/stride.git
```
5. From the `build/` directory, run:
```bash
msbuild /t:Build Stride.build
```
### Using `dotnet build`
`dotnet build` works without Visual Studio loaded — it auto-selects the Clang toolchain for the native C++ projects:
```bash
dotnet build build\Stride.sln
```
Stride auto-selects the native toolchain: MSVC when running under `MSBuild.exe` with the VS C++ tools loaded (VS Developer Command Prompt or IDE), Clang in every other case — including `dotnet build` from a Developer Command Prompt. See [SDK-GUIDE.md → Native Build Mode](SDK-GUIDE.md#native-build-mode-clang--msvc) for the full logic.
## Troubleshooting
* Test project errors are usually normal — GameStudio will start anyway.
* The Visual Studio extension may fail to build without the [Visual Studio SDK](https://learn.microsoft.com/en-us/visualstudio/extensibility/installing-the-visual-studio-sdk?view=vs-2026), but Game Studio will still start.
* Some changes require a system reboot — try that if you see `Could not find a compatible version of MSBuild` or `Path to dotnet executable is not set`.
* Make sure your `PATH` doesn't contain older MSBuild versions (e.g. `...\Microsoft Visual Studio\2019\BuildTools\MSBuild\Current\Bin` should be removed).
* If an older Visual Studio is installed alongside VS 2026, ensure you're using VS 2026 specifically.
* Ensure Git, Git LFS, and Visual Studio can reach the internet.
* If problems persist: close Visual Studio, clear the NuGet cache (`dotnet nuget locals all --clear`), delete `.vs` inside `build/` and the files in `bin/packages/`, kill any running `msbuild`/`dotnet` processes, then rebuild.
## Further Reading
- [SDK-GUIDE.md](SDK-GUIDE.md) — Stride build SDK internals (target structure, project SDK selection, native build modes)
build/docs/SDK-GUIDE.md → docs/build/SDK-GUIDE.md
Vendored
View File
sources/Directory.Build.props
+1 -1
View File
@@ -6,7 +6,7 @@
Therefore $(StrideRoot) is available within SDK files and for the closing
targets <Import> at the bottom of project files, but NOT for the opening
props <Import> (which uses GetDirectoryNameOfFileAbove to locate Sdk.props
without any pre-set property). See build/docs/SDK-GUIDE.md for details. -->
without any pre-set property). See docs/build/SDK-GUIDE.md for details. -->
<StrideRoot>$([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)../'))</StrideRoot>
</PropertyGroup>
</Project>
sources/README.md
+2 -2
View File
@@ -3,7 +3,7 @@ Stride Sources
## Build System
All Stride projects import the MSBuild SDK files directly from source. The props import uses `GetDirectoryNameOfFileAbove` to locate `Directory.Build.props` without relying on any pre-set property; the targets import uses `$(StrideRoot)` (set by `sources/Directory.Build.props`, available by that point in the evaluation). See [SDK-GUIDE.md](../build/docs/SDK-GUIDE.md) for details.
All Stride projects import the MSBuild SDK files directly from source. The props import uses `GetDirectoryNameOfFileAbove` to locate `Directory.Build.props` without relying on any pre-set property; the targets import uses `$(StrideRoot)` (set by `sources/Directory.Build.props`, available by that point in the evaluation). See [SDK-GUIDE.md](../docs/build/SDK-GUIDE.md) for details.
Three SDK packages are defined in `sources/sdk/`:
@@ -13,7 +13,7 @@ Three SDK packages are defined in `sources/sdk/`:
| **Stride.Build.Sdk.Editor** | Additional properties for editor/presentation projects |
| **Stride.Build.Sdk.Tests** | Test infrastructure — xunit integration, test launcher code generation |
For detailed SDK documentation, see [SDK-GUIDE.md](../build/docs/SDK-GUIDE.md).
For detailed SDK documentation, see [SDK-GUIDE.md](../docs/build/SDK-GUIDE.md).
## Folders and Projects Layout
sources/engine/Stride.Graphics/SilkNetResolverFix.cs
+1 -1
View File
@@ -14,7 +14,7 @@ namespace Stride.Graphics;
/// Works around Silk.NET's DefaultPathResolver having a hardcoded list of Linux distro RIDs
/// for native library fallback resolution. Distros not in the list (e.g. Ubuntu) fail to find
/// native libs in runtimes/linux-x64/native/.
/// See build/docs/silk-net-runtimesfolder-issue.md
/// See docs/build/silk-net-runtimesfolder-issue.md
/// </summary>
internal static class SilkNetResolverFix
{
sources/native/Stride.Native.targets
+8
View File
@@ -27,9 +27,17 @@
<!--<StrideNativeOutputPath>$([MSBuild]::MakeRelative('$(OutputPath)', '$(StridePackageStridePlatformBin)\'))</StrideNativeOutputPath>-->
<AllowedOutputExtensionsInPackageBuildOutputFolder>.so; .a; $(AllowedOutputExtensionsInPackageBuildOutputFolder)</AllowedOutputExtensionsInPackageBuildOutputFolder>
<!-- Auto-disable Windows ARM64 native build in MSVC mode if the VS ARM64 toolset isn't installed.
Clang mode always supports ARM64 via bundled clang+lld targeting aarch64-pc-windows-msvc. -->
<_StrideArm64ToolsetMissing Condition="'$(StrideNativeWindowsArm64Enabled)' == '' And '$(StrideNativeBuildModeMSVC)' == 'true' And !Exists('$(VCToolsInstallDir)bin\Hostx64\arm64\cl.exe')">true</_StrideArm64ToolsetMissing>
<StrideNativeWindowsArm64Enabled Condition="'$(StrideNativeWindowsArm64Enabled)' == '' And '$(_StrideArm64ToolsetMissing)' == 'true'">false</StrideNativeWindowsArm64Enabled>
<StrideNativeWindowsArm64Enabled Condition="'$(StrideNativeWindowsArm64Enabled)' == ''">true</StrideNativeWindowsArm64Enabled>
</PropertyGroup>
<Target Name="_StrideWarnArm64ToolsetMissing" BeforeTargets="Build" Condition="'$(_StrideArm64ToolsetMissing)' == 'true' And '$(StrideNativeOutputName)' != ''">
<Warning Text="[Stride] Windows ARM64 native build skipped: MSVC ARM64 toolset (cl.exe) not found under '$(VCToolsInstallDir)bin\Hostx64\arm64\'. Install 'MSVC v145 ARM64/ARM64EC build tools' from the VS installer, or set -p:StrideNativeWindowsArm64Enabled=false to silence this warning." />
</Target>
<Choose>
<When Condition="'$(TargetFramework)' == '$(StrideFrameworkUWP)'">
<PropertyGroup>
sources/sdk/README.md
+2 -2
View File
@@ -30,7 +30,7 @@ The SDK internal cross-references (`Stride.Build.Sdk.Editor` -> `Stride.Build.Sd
## Reverting to Full SDK Mode
See the "Reverting to full-SDK style" section in `build/docs/SDK-GUIDE.md` for complete instructions.
See the "Reverting to full-SDK style" section in `docs/build/SDK-GUIDE.md` for complete instructions.
## Building the SDK Packages
@@ -40,4 +40,4 @@ The packages are only needed when testing NuGet package distribution or revertin
dotnet build sources/sdk/Stride.Build.Sdk.slnx
```
For detailed documentation, see [build/docs/SDK-GUIDE.md](../../build/docs/SDK-GUIDE.md).
For detailed documentation, see [docs/build/SDK-GUIDE.md](../../docs/build/SDK-GUIDE.md).
sources/sdk/Stride.Build.Sdk/README.md
+1 -1
View File
@@ -13,4 +13,4 @@ This is the base SDK used by all Stride source projects via `<Project Sdk="Strid
This package is for building the Stride engine itself. It is not intended for end-user game projects.
See [SDK-GUIDE.md](https://github.com/stride3d/stride/blob/master/build/docs/SDK-GUIDE.md) for documentation.
See [SDK-GUIDE.md](https://github.com/stride3d/stride/blob/master/docs/build/SDK-GUIDE.md) for documentation.
sources/sdk/Stride.Build.Sdk/Sdk/Sdk.props
+1 -1
View File
@@ -20,7 +20,7 @@
Rule: Properties defined in the user's .csproj are NOT visible here.
Move conditional logic to Sdk.targets instead.
See: build/docs/SDK-GUIDE.md#property-evaluation-order
See: docs/build/SDK-GUIDE.md#property-evaluation-order
================================================================
-->
sources/sdk/Stride.Build.Sdk/Sdk/Sdk.targets
+1 -1
View File
@@ -22,7 +22,7 @@
Rule: User properties from .csproj ARE visible here.
This is where conditional logic belongs.
See: build/docs/SDK-GUIDE.md#property-evaluation-order
See: docs/build/SDK-GUIDE.md#property-evaluation-order
================================================================
-->