docs: rewrite Building-Locally.md for clarity

Restructure the document into a logical flow:
1. Prerequisites — tools (winget), WDK download link, repo clone
2. Building the Samples — NuGet, EWDK, WDK MSI/winget subsections with -RunMode intro
3. Expected Output — build plan and completion summary
4. Ways to Run — common Build-Samples.ps1 invocations
5. Additional Notes — pre-release WDK, usbview .NET packs, NuGet version pinning

Co-authored-by: Copilot <[email protected]>

1 files changed, 101 insertions, 137 deletions

diff --git a/Building-Locally.md b/Building-Locally.md
index 645e9a61..290d5954 100644
--- a/Building-Locally.md
+++ b/Building-Locally.md
@@ -1,165 +1,84 @@
-# How to build locally
+# Building Driver Samples Locally
 
-## Step 1: Install Tools
+## Prerequisites
 
-```powershell
-winget install --id Microsoft.Powershell --source winget
-winget install --id Git.Git --source winget
-```
+### Required tools
 
-For using WDK NuGet feed based build additionally:
+Install PowerShell and Git if you don't have them already:
 
 ```powershell
-winget install --id Microsoft.NuGet --source winget
-```
-
----
-
-## Step 2: Optional: Disable Strong Name Validation
-
-When: This step is only required if you will be using pre-release versions of the WDK.
-
-As per https://learn.microsoft.com/en-us/windows-hardware/drivers/installing-preview-versions-wdk :
-
-Run the following commands from an elevated command prompt to disable strong name validation:
-
-```
-reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\StrongName\Verification\*,31bf3856ad364e35 /v TestPublicKey /t REG_SZ /d 00240000048000009400000006020000002400005253413100040000010001003f8c902c8fe7ac83af7401b14c1bd103973b26dfafb2b77eda478a2539b979b56ce47f36336741b4ec52bbc51fecd51ba23810cec47070f3e29a2261a2d1d08e4b2b4b457beaa91460055f78cc89f21cd028377af0cc5e6c04699b6856a1e49d5fad3ef16d3c3d6010f40df0a7d6cc2ee11744b5cfb42e0f19a52b8a29dc31b0 /f
-
-reg add HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\StrongName\Verification\*,31bf3856ad364e35 /v TestPublicKey /t REG_SZ /d 00240000048000009400000006020000002400005253413100040000010001003f8c902c8fe7ac83af7401b14c1bd103973b26dfafb2b77eda478a2539b979b56ce47f36336741b4ec52bbc51fecd51ba23810cec47070f3e29a2261a2d1d08e4b2b4b457beaa91460055f78cc89f21cd028377af0cc5e6c04699b6856a1e49d5fad3ef16d3c3d6010f40df0a7d6cc2ee11744b5cfb42e0f19a52b8a29dc31b0 /f
+winget install --id Microsoft.Powershell --source winget
+winget install --id Git.Git --source winget
 ```
 
----
-
-## Step 3: Optional: Install Microsoft .NET Framework 4.7.2 Targeting Pack and Microsoft .NET Framework 4.8.1 SDK
+### Install a supported version of the WDK
 
-When: This step is only required to build sample usb\usbview .
+See [Download the Windows Driver Kit (WDK)](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) for all available installation options (NuGet packages, MSI installer, EWDK ISO).
 
-### Option A: Install VS Components
-
-Easy: If you will install Visual Studio (see later) you may at that point select to add both of following individual components:
-* .NET Framework 4.7.2 targeting pack
-* .NET Framework 4.8.1 SDK
-
-### Option B: Use EWDK
-
-Easy: If you use EWDK, then all necessary prequisites are included.
-
-### Option C: Install Developer Pack
-
-Hardest: Install from https://aka.ms/msbuild/developerpacks -> '.NET Framework' -> 'Supported versions' both of following packages:
-* .NET Framework 4.7.2 -> Developer Pack 
-* .NET Framework 4.8.1 -> Developer Pack 
-
-This will install following Apps:
-* Microsoft .NET Framework 4.7.2 SDK
-* Microsoft .NET Framework 4.7.2 Targeting Pack
-* Microsoft .NET Framework 4.7.2 Targeting Pack (ENU)
-* Microsoft .NET Framework 4.8.1 SDK
-* Microsoft .NET Framework 4.8.1 Targeting Pack
-* Microsoft .NET Framework 4.8.1 Targeting Pack (ENU)
-
----
-
-## Step 4: Clone Windows Driver Samples and checkout relevant branch
+### Clone the repository
 
 ```powershell
-cd "path\to\your\repos"
 git clone --recurse-submodules "https://github.com/microsoft/Windows-driver-samples.git"
 cd ".\Windows-driver-samples"
 ```
 
-If you are planning to use in-market WDK, then you would typically want to use the 'main' branch:
-
-```
-git checkout main
-```
-
-If you are planning to use a WDK Preview or WDK EEAP release, then you would typically want to use the 'develop' branch:
+Use `main` for in-market WDK releases, `develop` for WDK Preview / EEAP builds:
 
-```
-git checkout develop
+```powershell
+git checkout main      # stable / in-market
+git checkout develop   # preview / EEAP
 ```
 
 ---
 
-## Step 5: Create a "driver build environment"
+## Building the Samples
 
-To build the Windows Driver Samples you need a "driver build environment".  In essence an environment that consist of following prerequisites:
-* Visual Studio Build Tools including tools such as for example cl.exe and link.exe .
-* The Windows Software Development Kit.
-* The Windows Driver Kit.
-
-### Option A: Use WDK NuGet Packages
-
-* See [Download the Windows Driver Kit (WDK)](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) for instructions on how to install Visual Studio, but only complete `Step 1`.  You do not need to install the SDK or the WDK.
-* Launch a "Developer Command Prompt for VS 2022".
-* Restore WDK packages from feed :
+The script auto-detects which WDK environment is active. Use `-RunMode` to force a specific one if needed:
 
 ```powershell
-cd "path\to\your\repos\Windows-driver-samples"
-nuget restore -PackagesDirectory ".\packages"
+.\Build-Samples.ps1 -RunMode NuGet    # force NuGet
+.\Build-Samples.ps1 -RunMode EWDK     # force EWDK
+.\Build-Samples.ps1 -RunMode WDK      # force WDK
 ```
 
-* When this is done you should have a .\packages folder that looks like example below:
+### NuGet Package
+
+Install NuGet if you don't have it:
 
 ```powershell
-cd "path\to\your\repos\Windows-driver-samples"
-dir /b packages
-Microsoft.Windows.SDK.CPP.10.0.26000.1
-Microsoft.Windows.SDK.CPP.x64.10.0.26000.1
-Microsoft.Windows.SDK.CPP.arm64.10.0.26000.1
-Microsoft.Windows.WDK.x64.10.0.26000.1
-Microsoft.Windows.WDK.arm64.10.0.26000.1
+winget install --id Microsoft.NuGet --source winget
 ```
 
-### Option B: Use the Windows Driver Kit
-
-* Here you will install each of above prerequisites one at a time.
-* See [Download the Windows Driver Kit (WDK)](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) for instructions on how to install Visual Studio, SDK, and WDK.
-* Launch a "Developer Command Prompt for VS 2022".
-
-### Option C: Use an Enterprise WDK
-
-* You can also simply use the Enterprise WDK (EWDK), a standalone, self-contained command-line environment for building drivers that contains all prerequisites in one combined ISO.
-* See [Download the Windows Driver Kit (WDK)](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) for instructions on how to download the EWDK.
-* Mount ISO image
-* Open a terminal
-* `.\LaunchBuildEnv`
-
----
-
-## Step 6: Build all samples
+Restore the WDK packages and build from Powershell:
 
 ```powershell
+nuget restore -PackagesDirectory ".\packages"
 pwsh
-.\Build-Samples
+.\Build-Samples.ps1
 ```
-Above builds all samples for all configurations and platforms.
-
-You can refine what exact samples to build, what configurations, and platforms to build. Here are a few examples:
 
-```powershell
-# Get Help:
-Get-Help .\Build-Samples
+### EWDK
 
-# Build all solutions for all flavors with builds running in parallel:
-.\Build-Samples
+Mount the EWDK ISO, open a terminal in the mounted drive, launch the build environment, then build:
 
-# Build with Verbose output (print start and finish of each sample):
-.\Build-Samples -Verbose
+```powershell
+.\LaunchBuildEnv
+pwsh
+.\Build-Samples.ps1
+```
 
-# Build without massive parallelism (slow, but good for debugging):
-.\Build-Samples -ThrottleLimit 1
+### WDK MSI/winget
 
-# Build all samples inside the 'tools' folder using wildcards:
-.\Build-Samples -Samples 'tools.*'
+Build the samples from PowerShell:
 
-# Build specific samples for only 'Debug|x64':
-.\Build-Samples -Samples 'tools.sdv.samples.sampledriver' -Configurations 'Debug' -Platforms 'x64'
+```powershell
+pwsh
+.\Build-Samples.ps1
 ```
 
-Example of expected output:
+---
+
+## Expected Output
 
 ```
 --- WDK Sample Build Plan ------------------------------------------
@@ -209,31 +128,76 @@ Building all combinations...
 
 ---
 
-## 7: NuGet - Additional Notes
+## Ways to Run
 
-To restore a specific version of our WDK NuGet packages:
+```powershell
+# Show full parameter reference:
+Get-Help .\Build-Samples.ps1 -Detailed
+
+# Build everything (all samples, configurations, platforms):
+.\Build-Samples.ps1
+
+# Verbose output — prints start/finish of each sample:
+.\Build-Samples.ps1 -Verbose
 
-Follow these steps before running "nuget restore" command:
-* Open the .\packages.config file and update the full version (including the branch if required) in all three entries.
-* Open the .\Directory.build.props file and update the version and build of the package with the same values as in previous step.
-* Open .\Build-Samples.ps1 and check the NuGet build number logic (used by .\exclusions.csv and for determining infverif flags)
-* Now you can run "nuget restore"
+# Limit parallelism (useful for debugging build failures):
+.\Build-Samples.ps1 -ThrottleLimit 1
 
-A few examples of how to interact with nuget:
+# Build only samples inside the 'tools' folder:
+.\Build-Samples.ps1 -Samples 'tools.*'
+
+# Build a specific sample for Debug|x64 only:
+.\Build-Samples.ps1 -Samples 'tools.sdv.samples.sampledriver' -Configurations 'Debug' -Platforms 'x64'
+```
+
+---
+
+## Additional Notes
+
+### Pre-release WDK: disable strong name validation
+
+Required only when using pre-release WDK versions. Run from an elevated command prompt:
+
+```
+reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\StrongName\Verification\*,31bf3856ad364e35 /v TestPublicKey /t REG_SZ /d 00240000048000009400000006020000002400005253413100040000010001003f8c902c8fe7ac83af7401b14c1bd103973b26dfafb2b77eda478a2539b979b56ce47f36336741b4ec52bbc51fecd51ba23810cec47070f3e29a2261a2d1d08e4b2b4b457beaa91460055f78cc89f21cd028377af0cc5e6c04699b6856a1e49d5fad3ef16d3c3d6010f40df0a7d6cc2ee11744b5cfb42e0f19a52b8a29dc31b0 /f
+
+reg add HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\StrongName\Verification\*,31bf3856ad364e35 /v TestPublicKey /t REG_SZ /d 00240000048000009400000006020000002400005253413100040000010001003f8c902c8fe7ac83af7401b14c1bd103973b26dfafb2b77eda478a2539b979b56ce47f36336741b4ec52bbc51fecd51ba23810cec47070f3e29a2261a2d1d08e4b2b4b457beaa91460055f78cc89f21cd028377af0cc5e6c04699b6856a1e49d5fad3ef16d3c3d6010f40df0a7d6cc2ee11744b5cfb42e0f19a52b8a29dc31b0 /f
+```
+
+See [Installing preview versions of the WDK](https://learn.microsoft.com/en-us/windows-hardware/drivers/installing-preview-versions-wdk) for more details.
+
+### Building `usb\usbview`: .NET Framework targeting packs
+
+The `usb\usbview` sample requires .NET Framework 4.7.2 and 4.8.1. Choose one option:
+
+- **VS installer** — add the *.NET Framework 4.7.2 targeting pack* and *.NET Framework 4.8.1 SDK* individual components when installing Visual Studio.
+- **EWDK** — all required prerequisites are already included.
+- **Manual** — download both Developer Packs from https://aka.ms/msbuild/developerpacks.
+
+### NuGet: restoring a specific WDK version
+
+To pin a specific WDK NuGet version before running `nuget restore`:
+
+1. Open `.\packages.config` and update the version in all entries.
+2. Open `.\Directory.build.props` and set the same version.
+3. Run `nuget restore -PackagesDirectory ".\packages"`.
+
+Useful NuGet commands:
 
 ```powershell
-# To add an alternative online NuGet source:
-nuget sources add -Name "MyNuGetFeed" -Source "https://nugetserver.com/_packaging/feedname/nuget/v3/index.json"
+# Add an online feed:
+nuget sources add -Name "MyFeed" -Source "https://nugetserver.com/_packaging/feedname/nuget/v3/index.json"
 
-# To add an alternative local NuGet source:
-nuget sources add -Name "MyNuGetFeed" -Source "\\path\to\mylocalrepo"
+# Add a local feed:
+nuget sources add -Name "MyFeed" -Source "\\path\to\mylocalrepo"
 
-# To remove an alternative NuGet source:
-nuget sources remove -Name "MyNuGetFeed"
+# Remove a feed:
+nuget sources remove -Name "MyFeed"
 
-# To enumerate NuGet locals:
+# List local caches:
 nuget locals all -list
 
-# To clear NuGet locals:
+# Clear local caches:
 nuget locals all -clear
 ```
+