Clarify that MSBuild is required in most cases

Author: Kryptos-FR

build/docs/00-SUMMARY.md

@@ -141,7 +141,8 @@ dotnet build MyGame.Windows.csproj -p:StrideGraphicsApis=Vulkan
 
 ### Build engine with single API (fast development)
 ```bash
-dotnet build build\Stride.sln -p:StrideGraphicsApis=Direct3D11 -p:StrideSkipUnitTests=true
+# Note: Use msbuild (not dotnet build) as the engine contains C++/CLI projects
+msbuild build\Stride.sln -p:StrideGraphicsApis=Direct3D11 -p:StrideSkipUnitTests=true
 ```
 
 ### Full official build (all APIs)
@@ -172,6 +173,10 @@ dotnet build sources\core\Stride.Core\Stride.Core.csproj
 - `sources/targets/Stride.targets` - Version replacement, shader generation
 - `sources/targets/Stride.GraphicsApi.Dev.targets` - Graphics API inner builds
 
+## Important: MSBuild vs dotnet build
+
+> **The Stride engine contains C++/CLI projects that require `msbuild` to build.** Use `msbuild` (not `dotnet build`) for building the full engine/editor solutions (`build\Stride.sln`). Individual Core library projects and game projects can use `dotnet build`.
+
 ## For New Contributors
 
 **Start here:**
@@ -219,14 +224,14 @@ Create `Directory.Build.props` in repository root:
 
 **Testing changes:**
 ```bash
-# Test all platforms (if possible)
-dotnet build build\Stride.sln -f:net10.0           # Desktop
-dotnet build build\Stride.sln -f:net10.0-android   # Android
-dotnet build build\Stride.sln -f:net10.0-ios       # iOS
+# Test all platforms (if possible) - use msbuild for full engine
+msbuild build\Stride.sln -f:net10.0           # Desktop
+msbuild build\Stride.sln -f:net10.0-android   # Android
+msbuild build\Stride.sln -f:net10.0-ios       # iOS
 
 # Test all Graphics APIs
-dotnet build build\Stride.sln -p:StrideGraphicsApis=Direct3D11
-dotnet build build\Stride.sln -p:StrideGraphicsApis=Vulkan
+msbuild build\Stride.sln -p:StrideGraphicsApis=Direct3D11
+msbuild build\Stride.sln -p:StrideGraphicsApis=Vulkan
 
 # Test full build
 msbuild build\Stride.build -t:BuildWindows

build/docs/01-build-system-overview.md

@@ -3,6 +3,8 @@
 ## Introduction
 
 The Stride game engine uses a complex MSBuild-based build system designed to support:
+
+> **Important Note:** The Stride engine contains C++/CLI projects (for native library interop) that require **`msbuild`** to build. When building the full engine or editor solutions, you must use `msbuild`, not `dotnet build`. However, individual Core library projects and game projects can use `dotnet build`.
 - **6 platforms**: Windows, Linux, macOS, Android, iOS, and UWP
 - **5 graphics APIs**: Direct3D 11, Direct3D 12, OpenGL, OpenGLES, and Vulkan
 - **Cross-compilation**: Build for different platforms from a single host

build/docs/04-build-scenarios.md

@@ -2,6 +2,8 @@
 
 This document provides practical examples of common build scenarios in Stride.
 
+> **Important:** The Stride engine contains C++/CLI projects that require **`msbuild`** to build. Use `msbuild` for building the full engine/editor solutions (`build\Stride.sln`, etc.). You can use `dotnet build` for individual Core library projects or game projects.
+
 ## Table of Contents
 
 - [Quick Reference](#quick-reference)

build/docs/05-developer-workflow.md

@@ -2,6 +2,8 @@
 
 Tips and best practices for efficient daily development on the Stride game engine.
 
+> **Important:** The Stride engine contains C++/CLI projects that require **`msbuild`** to build. Use `msbuild` for building the full engine/editor solutions (`build\Stride.sln`, etc.). You can use `dotnet build` for individual Core library projects or game projects.
+
 ## Table of Contents
 
 - [Initial Setup](#initial-setup)
@@ -25,8 +27,8 @@ cd stride
 dotnet restore build\Stride.sln
 
 # Initial build (choose fastest option for your platform)
-# Windows:
-dotnet build build\Stride.sln -p:StrideGraphicsApis=Direct3D11 -p:StrideSkipUnitTests=true
+# Windows (use msbuild due to C++/CLI projects):
+msbuild build\Stride.sln -p:StrideGraphicsApis=Direct3D11 -p:StrideSkipUnitTests=true
 
 # Linux:
 dotnet build build/Stride.sln -p:StrideGraphicsApis=OpenGL -p:StrideSkipUnitTests=true
@@ -73,8 +75,8 @@ git pull origin main
 # 2. Restore (only if .csproj changed)
 dotnet restore build\Stride.sln
 
-# 3. Build (incremental)
-dotnet build build\Stride.sln --no-restore
+# 3. Build (incremental, use msbuild for full engine)
+msbuild build\Stride.sln --no-restore
 ```
 
 ### Working on Specific Project
@@ -91,8 +93,8 @@ dotnet build sources\engine\Stride.Graphics\Stride.Graphics.csproj --no-dependen
 
 ```bash
 # Clean and rebuild
-dotnet clean build\Stride.sln
-dotnet build build\Stride.sln
+msbuild build\Stride.sln -t:Clean
+msbuild build\Stride.sln
 ```
 
 ### Update NuGet Packages
@@ -124,11 +126,11 @@ export StrideGraphicsApis=Vulkan
 ### Switch APIs Temporarily
 
 ```bash
-# Build with specific API
-dotnet build build\Stride.sln -p:StrideGraphicsApis=Direct3D12
+# Build with specific API (use msbuild for full engine)
+msbuild build\Stride.sln -p:StrideGraphicsApis=Direct3D12
 
 # Back to your default
-dotnet build build\Stride.sln
+msbuild build\Stride.sln
 ```
 
 ### Test Multiple APIs
@@ -140,7 +142,7 @@ dotnet build build\Stride.sln
 $apis = "Direct3D11", "Direct3D12", "Vulkan", "OpenGL"
 foreach ($api in $apis) {
     Write-Host "Testing $api..." -ForegroundColor Green
-    dotnet build build\Stride.sln -p:StrideGraphicsApis=$api
+    msbuild build\Stride.sln -p:StrideGraphicsApis=$api
     dotnet test build\Stride.sln -p:StrideGraphicsApis=$api --no-build
 }
 ```
@@ -166,7 +168,7 @@ Create `Directory.Build.props` as shown in [Initial Setup](#initial-setup).
 **Solution 3: Command line**
 
 ```bash
-dotnet build build\Stride.sln -p:StrideDefaultGraphicsApiDesignTime=Vulkan
+msbuild build\Stride.sln -p:StrideDefaultGraphicsApiDesignTime=Vulkan
 ```
 
 Then reload solution in Visual Studio.
@@ -254,7 +256,7 @@ git tag v4.3.0.2
 git push origin v4.3.0.2
 
 # Rebuild to update version
-dotnet build build\Stride.sln
+msbuild build\Stride.sln
 ```
 
 ### Create NuGet Package Locally
@@ -281,7 +283,7 @@ build.bat  # or build.sh on Linux
 copy lib\* ..\..\Bin\Windows\
 
 # Rebuild engine
-dotnet build build\Stride.sln
+msbuild build\Stride.sln
 ```
 
 ### Regenerate Solution Files
@@ -450,17 +452,17 @@ Console.WriteLine("Compiled with Direct3D 11 support");
 
 ```bash
 # Use all CPU cores
-dotnet build build\Stride.sln -m
+msbuild build\Stride.sln -m
 
 # Limit to 4 cores (if thermal throttling)
-dotnet build build\Stride.sln -m:4
+msbuild build\Stride.sln -m:4
 ```
 
 ### Incremental Builds
 
 ```bash
 # Skip restore if no package changes
-dotnet build build\Stride.sln --no-restore
+msbuild build\Stride.sln --no-restore
 
 # Skip dependency checks (dangerous!)
 dotnet build MyProject.csproj --no-dependencies
@@ -479,10 +481,10 @@ Use a persistent build cache:
 
 ```bash
 # Minimal output (faster, harder to debug)
-dotnet build build\Stride.sln -v:q
+msbuild build\Stride.sln -v:q
 
 # Normal (default)
-dotnet build build\Stride.sln -v:n
+msbuild build\Stride.sln -v:n
 ```
 
 ## Workflow Aliases (PowerShell)
@@ -491,8 +493,9 @@ Add to your PowerShell profile (`$PROFILE`):
 
 ```powershell
 # Stride build aliases
+# Note: Use msbuild due to C++/CLI projects
 function Stride-Build { 
-    dotnet build build\Stride.sln -p:StrideGraphicsApis=Direct3D11 -p:StrideSkipUnitTests=true 
+    msbuild build\Stride.sln -p:StrideGraphicsApis=Direct3D11 -p:StrideSkipUnitTests=true 
 }
 
 function Stride-Build-All { 
@@ -522,7 +525,8 @@ Add to `~/.bashrc` or `~/.zshrc`:
 
 ```bash
 # Stride build aliases
-alias stride-build='dotnet build build/Stride.sln -p:StrideGraphicsApis=OpenGL -p:StrideSkipUnitTests=true'
+# Note: Use msbuild due to C++/CLI projects
+alias stride-build='msbuild build/Stride.sln -p:StrideGraphicsApis=OpenGL -p:StrideSkipUnitTests=true'
 alias stride-build-all='msbuild build/Stride.build -t:BuildLinux'
 alias stride-clean='dotnet clean build/Stride.sln'
 alias stride-test='dotnet test build/Stride.sln --no-build'
@@ -564,8 +568,8 @@ dotnet restore build\Stride.sln --force
 
 ```bash
 # Clean build
-dotnet clean build\Stride.sln
-dotnet build build\Stride.sln
+msbuild build\Stride.sln -t:Clean
+msbuild build\Stride.sln
 ```
 
 ## Best Practices

build/docs/06-troubleshooting.md

@@ -21,9 +21,9 @@ Run these commands when encountering issues:
 # 1. Check configuration
 dotnet build MyProject.csproj -t:StrideDiagnostics
 
-# 2. Clean build
-dotnet clean build\Stride.sln
-dotnet build build\Stride.sln
+# 2. Clean build (use msbuild for full engine)
+msbuild build\Stride.sln -t:Clean
+msbuild build\Stride.sln
 
 # 3. Force restore
 dotnet restore build\Stride.sln --force
@@ -88,9 +88,11 @@ error MSB4126: The specified solution configuration "Release|Mixed Platforms" is
 **Solution:**
 
 ```bash
-# Use dotnet msbuild (recommended)
-dotnet --version  # Check .NET SDK version
-dotnet build build\Stride.sln
+# Check .NET SDK version
+dotnet --version
+
+# Use msbuild (required for C++/CLI projects)
+msbuild build\Stride.sln
 
 # Or use latest MSBuild
 "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" build\Stride.sln
@@ -123,8 +125,8 @@ grep -i "error" build.log | head -20
 
 ```bash
 # 1. Clean and rebuild
-dotnet clean build\Stride.sln
-dotnet build build\Stride.sln
+msbuild build\Stride.sln -t:Clean
+msbuild build\Stride.sln
 
 # 2. Disable assembly processor temporarily (for diagnosis)
 dotnet build MyProject.csproj -p:StrideAssemblyProcessor=false
@@ -386,8 +388,8 @@ sudo apt-get install libx11-dev libxrandr-dev libxi-dev
 # Fedora/RHEL
 sudo dnf install libX11-devel libXrandr-devel libXi-devel
 
-# Then rebuild
-dotnet build build/Stride.sln
+# Then rebuild (use msbuild for full engine)
+msbuild build/Stride.sln
 ```
 
 ## NuGet and Restore Issues
@@ -505,23 +507,23 @@ grep "Time Elapsed" build.log | sort -k3 -rn | head -10
 1. **Building all Graphics APIs:**
 
 ```bash
-# Build single API only
-dotnet build build\Stride.sln -p:StrideGraphicsApis=Direct3D11
+# Build single API only (use msbuild for full engine)
+msbuild build\Stride.sln -p:StrideGraphicsApis=Direct3D11
 # ~5x faster
 ```
 
 2. **Unit tests running:**
 
 ```bash
 # Skip unit tests
-dotnet build build\Stride.sln -p:StrideSkipUnitTests=true
+msbuild build\Stride.sln -p:StrideSkipUnitTests=true
 ```
 
 3. **Building unnecessary projects:**
 
 ```bash
-# Use solution filter
-dotnet build build\Stride.Runtime.slnf  # Only runtime projects
+# Use solution filter (use msbuild for engine builds)
+msbuild build\Stride.Runtime.slnf
 ```
 
 4. **Antivirus scanning:**
@@ -591,8 +593,8 @@ dotnet restore build\Stride.sln
 rm -rf .vs  # or rmdir /s /q .vs on Windows
 
 # 2. Rebuild project
-dotnet clean build\Stride.sln
-dotnet build build\Stride.sln
+msbuild build\Stride.sln -t:Clean
+msbuild build\Stride.sln
 
 # 3. Reload solution in Visual Studio
 

build/docs/07-improvement-proposals.md

@@ -411,11 +411,11 @@ grep -r "StrideObsolete" build/ sources/targets/
 **Usage:**
 
 ```bash
-# Dev build (fast)
-dotnet build build\Stride.sln
+# Dev build (fast, use msbuild for full engine)
+msbuild build\Stride.sln
 
 # CI build (thorough)
-dotnet build build\Stride.sln -p:StrideBuildProfile=CI
+msbuild build\Stride.sln -p:StrideBuildProfile=CI
 ```
 
 **Benefits:**

build/docs/README.md

@@ -19,6 +19,8 @@ This directory contains comprehensive documentation about the Stride build syste
 
 ## Quick Start
 
+> **Important:** The Stride engine contains C++/CLI projects that require **`msbuild`** to build. Use `msbuild` for building the full engine/editor (`build\Stride.sln`). You can use `dotnet build` for individual Core library projects or game projects.
+
 ### Full Windows Build
 ```bash
 msbuild build\Stride.build -t:BuildWindows -m:1 -nr:false -v:m -p:StrideSkipUnitTests=true