1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
# Building Driver Samples Locally
## Prerequisites
### Required tools
Install PowerShell and Git if you don't have them already:
```powershell
winget install --id Microsoft.Powershell --source winget
winget install --id Git.Git --source winget
```
### Install a supported version of the WDK
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).
### Clone the repository
```powershell
git clone --recurse-submodules "https://github.com/microsoft/Windows-driver-samples.git"
cd ".\Windows-driver-samples"
```
### Environment specific requisites
- If you are using the WDK via **NuGet**: install NuGet and restore the packages:
```powershell
winget install --id Microsoft.NuGet --source winget
nuget restore -PackagesDirectory ".\packages"
```
- If you are using the WDK via **EWDK**: mount the EWDK ISO, open a terminal in the mounted drive, and launch the build environment:
```powershell
.\LaunchBuildEnv
```
---
## Building the Samples
The `Build-Samples.ps1` script auto-detects which WDK environment is active and will build all the samples with all the configurations by default. Just run the following command from **PowerShell**:
```powershell
.\Build-Samples.ps1
```
---
## Expected Output
```
--- WDK Sample Build Plan ------------------------------------------
Environment: NuGet
Build Number: 26100
NuGet Version: 10.0.26100.1
WDK VS Component: 10.0.26100.1882
InfVerif Options: /samples
Samples: 132 (0 skipped)
Configurations: Debug, Release
Platforms: x64, arm64
Combinations: 528
Exclusions: 4
Parallelism: 60 jobs (12 cores x 5)
Disk Free (GB): ...
Wipe Outputs: False
--------------------------------------------------------------------
Progress legend:
T=Total B=Built R=Running P=Pending
S=Succeeded E=Excluded U=Unsupported F=Failed O=Sporadic
Building all combinations...
--- Build Complete -------------------------------------------------
Elapsed: 12m 42s
Disk Free (GB): ...
Samples: 132
Configurations: Debug, Release
Platforms: x64, arm64
Combinations: 528
Succeeded: 526
Excluded: 0
Unsupported: 2
Failed: 0
Sporadic: 0
Log directory: .\_logs
CSV report: .\_logs\_overview.csv
HTML report: .\_logs\_overview.htm
--------------------------------------------------------------------
```
---
## Ways to Run
```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
# Limit parallelism (useful for debugging build failures):
.\Build-Samples.ps1 -ThrottleLimit 1
# 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'
# Build every sample linking against an older WDK library set (default is the latest):
.\Build-Samples.ps1 -NtTargetVersion 10.0.22000
```
`-NtTargetVersion` selects the WDK **`_NT_TARGET_VERSION`** — the OS version of the libraries
the driver links against. It accepts the Windows build number (`10.0.<build>`) or the short
`<build>` tag (e.g. `10.0.22000` or `22000`); when omitted it uses the latest. The valid
values are **auto-discovered from the active WDK** — `Get-NtTargetVersions.ps1` parses the
WDK's `DriverGeneral.xml` rule — so a new WDK version is picked up automatically with no edits.
List what's available with:
```powershell
.\Get-NtTargetVersions.ps1
```
---
## Excluding samples from the build
Samples that are known not to build for a given environment are listed in `exclusions.csv`
at the repo root. Each row excludes a path (with wildcards) for specific
configuration/platform combinations, an optional WDK build-number range, and an optional
`_NT_TARGET_VERSION` range:
```
Path,Configurations,MinBuild,MaxBuild,MinNtTargetVersion,MaxNtTargetVersion,Reason
```
| Column | Meaning |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `Path` | Sample path (backslashes); supports `*`/`?` wildcards. |
| `Configurations` | `;`-separated `Config\|Platform` patterns, or `*` for all (e.g. `*\|ARM64`, `Debug\|x64`). |
| `MinBuild`/`MaxBuild` | Inclusive WDK build-number range; blank = unbounded. |
| `MinNtTargetVersion`/`MaxNtTargetVersion` | Inclusive `-NtTargetVersion` build-number range (e.g. `22621` matches `10.0.22621`); blank = unbounded. Use this for samples that fail only when linking against older libraries. |
| `Reason` | Human-readable explanation (keep this column last; quote it if it contains commas). |
A row is applied only when every populated condition matches the current run (path,
configuration/platform, WDK build-number range, and NT target-version range are AND-ed
together). Leave a column blank to ignore that dimension (the default for most rows).
For example, to exclude a sample (Debug builds only) when linking against the `10.0.22621`
library set or older, because it uses a newer API:
```
somepath,Debug|*,,,,22621,uses an API newer than the 10.0.22621 library
```
---
## 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
# Add an online feed:
nuget sources add -Name "MyFeed" -Source "https://nugetserver.com/_packaging/feedname/nuget/v3/index.json"
# Add a local feed:
nuget sources add -Name "MyFeed" -Source "\\path\to\mylocalrepo"
# Remove a feed:
nuget sources remove -Name "MyFeed"
# List local caches:
nuget locals all -list
# Clear local caches:
nuget locals all -clear
```
|
