Incremental improvements of the sample build system (microsoft#849)

.github/workflows/Code-Scanning.yml

@@ -48,10 +48,10 @@ jobs:
     - name: Retrieve and build all available solutions
       id: build-all-samples
       run: |
-          .\Build-AllSamples.ps1
+          .\Build-AllSamples.ps1 -Verbose
       env:
-        Configuration: ${{ matrix.configuration }}
-        Platform: ${{ matrix.platform }}
+        Configuration: Debug
+        Platform: x64
 
     - name: Perform CodeQL analysis
       uses: github/codeql-action/analyze@v2

Build-AllSamples.ps1

@@ -5,14 +5,17 @@ Builds all available sample solutions in the repository (excluding specific solu
 .DESCRIPTION
 This script searches for all available Visual Studio Solutions (.sln files) and attempts to run MSBuild to build them for the specified configurations and platforms.
 
+.PARAMETER Samples
+A regular expression matching the samples to be built.  Default is '' that matches all samples.  Examples include '^tools.' or '.dchu'.
+
 .PARAMETER Configurations
-A list of configurations to build samples under. Values available are "Debug" and "Release". By default, $env:Configuration will be used as the sole configuration to build for. If this value doesn't exist, "Debug" will be used instead.
+A list of configurations to build samples under. Values available are 'Debug' and 'Release'. By default, $env:Configuration will be used as the sole configuration to build for. If this environment variable is not set the default is 'Debug' and 'Release'.
 
 .PARAMETER Platforms
-A list of platforms to build samples under (e.g. "x64", "arm64"). By default, $env:Platform will be used as the sole platform to build for. If this value doesn't exist, "x64" will be used instead.
+A list of platforms to build samples under (e.g. 'x64', 'arm64'). By default, $env:Platform will be used as the sole platform to build for. If this environment variable is not set the default is 'x64' and'arm64'.
 
 .PARAMETER LogFilesDirectory
-Path to a directory where the log files will be written to. If not provided, outputs will be logged to the "_logs" directory within the current working directory.
+Path to a directory where the log files will be written to. If not provided, outputs will be logged to the '_logs' directory within the current working directory.
 
 .INPUTS
 None.
@@ -24,14 +27,15 @@ None.
 .\Build-AllSamples
 
 .EXAMPLE
-.\Build-AllSamples -Configurations 'Debug','Release' -Platforms 'x64','arm64' -LogFilesDirectory .\_logs
+.\Build-AllSamples -Samples '^tools.' -Configurations 'Debug','Release' -Platforms 'x64','arm64' -LogFilesDirectory .\_logs
 
 #>
 
 [CmdletBinding()]
 param(
-    [string[]]$Configurations = @([string]::IsNullOrEmpty($env:Configuration) ? "Debug" : $env:Configuration),
-    [string[]]$Platforms = @([string]::IsNullOrEmpty($env:Platform) ? "x64" : $env:Platform),
+    [string]$Samples = "",
+    [string[]]$Configurations = @([string]::IsNullOrEmpty($env:Configuration) ? ('Debug','Release') : $env:Configuration),
+    [string[]]$Platforms = @([string]::IsNullOrEmpty($env:Platform) ? ('x64','arm64') : $env:Platform),
     [string]$LogFilesDirectory = (Join-Path (Get-Location) "_logs")
 )
 
@@ -48,8 +52,15 @@ $sampleSet = @{}
 foreach ($file in $solutionFiles) {
     $dir = (Get-Item $file).DirectoryName
     $dir_norm = $dir.Replace($root, '').Trim('\').Replace('\', '.').ToLower()
-    Write-Verbose "`u{1F50E} Found sample [$dir_norm] at $dir"
-    $sampleSet[$dir_norm] = $dir
+    if($dir_norm -match ($Samples))
+    {
+        Write-Verbose "`u{1F50E} Found and included sample [$dir_norm] at $dir"
+        $sampleSet[$dir_norm] = $dir
+    }
+    else
+    {
+        Write-Verbose "`u{1F50E} Found and excluded sample [$dir_norm] at $dir"
+    }
 }
 
 

Build-SampleSet.ps1

@@ -19,12 +19,8 @@ Remove-Item  -Recurse -Path $LogFilesDirectory 2>&1 | Out-Null
 New-Item -ItemType Directory -Force -Path $LogFilesDirectory | Out-Null
 
 $NumberOfLogicalProcessors = (Get-CIMInstance -Class 'CIM_Processor' -Verbose:$false).NumberOfLogicalProcessors
-$SolutionsInParallel = 5 * $NumberOfLogicalProcessors
-
-Write-Verbose "Log files directory: $LogFilesDirectory"
-Write-Verbose "Results overview report: $sampleBuilderFilePath"
-Write-Verbose "Logical Processors: $NumberOfLogicalProcessors"
-Write-Verbose "Solutions in Parallel: $SolutionsInParallel"
+$Throttlefactor = 5
+$SolutionsInParallel = $Throttlefactor * $NumberOfLogicalProcessors
 
 $oldPreference = $ErrorActionPreference
 $ErrorActionPreference = "stop"
@@ -58,7 +54,15 @@ $jresult = @{
 
 $SolutionsTotal = $sampleSet.Count * $Configurations.Count * $Platforms.Count
 
-Write-Output "T: Total solutions: $SolutionsTotal"
+Write-Output ("Samples:              "+$sampleSet.Count)
+Write-Output ("Configurations:       "+$Configurations.Count+" ("+$Configurations+")")
+Write-Output ("Platforms:            "+$Platforms.Count+" ("+$Platforms+")")
+Write-Output "Combinations:         $SolutionsTotal"
+Write-Output "Logical Processors:   $NumberOfLogicalProcessors"
+Write-Output "Throttle factor:      $Throttlefactor"
+Write-Output "Throttle limit:       $SolutionsInParallel"
+Write-Output ""
+Write-Output "T: Combinations"
 Write-Output "B: Built"
 Write-Output "R: Build is running currently"
 Write-Output "P: Build is pending an available build slot"
@@ -68,7 +72,7 @@ Write-Output "E: Built and result was 'Excluded'"
 Write-Output "U: Built and result was 'Unsupported' (Platform and Configuration combination)"
 Write-Output "F: Built and result was 'Failed'"
 Write-Output ""
-Write-Output "Building driver solutions..."
+Write-Output "Building all combinations..."
 
 $Results = @()
 
@@ -137,7 +141,7 @@ $SampleSet.GetEnumerator() | ForEach-Object -ThrottleLimit $SolutionsInParallel
                 $SolutionsBuiltPercent = [Math]::Round(100 * ($SolutionsBuilt / $using:SolutionsTotal))
                 $TBRP = "T:" + ($SolutionsTotal) + "; B:" + (($using:jresult).SolutionsBuilt) + "; R:" + ($SolutionsRunning) + "; P:" + ($SolutionsPending)
                 $rstr = "S:" + (($using:jresult).SolutionsSucceeded) + "; E:" + (($using:jresult).SolutionsExcluded) + "; U:" + (($using:jresult).SolutionsUnsupported) + "; F:" + (($using:jresult).SolutionsFailed)
-                Write-Progress -Activity "Building driver solutions" -Status "$SolutionsBuilt of $using:SolutionsTotal solutions built ($SolutionsBuiltPercent%) | $TBRP | $rstr" -PercentComplete $SolutionsBuiltPercent
+                Write-Progress -Activity "Building combinations" -Status "$SolutionsBuilt of $using:SolutionsTotal combinations built ($SolutionsBuiltPercent%) | $TBRP | $rstr" -PercentComplete $SolutionsBuiltPercent
             }
             finally {
                 ($using:jresult).lock.ReleaseMutex()
@@ -156,11 +160,11 @@ $SampleSet.GetEnumerator() | ForEach-Object -ThrottleLimit $SolutionsInParallel
 $sw.Stop()
 
 if ($failSet.Count -gt 0) {
-    Write-Output "Some samples were built with errors:"
+    Write-Output "Some combinations were built with errors:"
     foreach ($failedSample in $failSet) {
         Write-Output "$failedSample"
     }
-    Write-Error "Some samples were built with errors."
+    Write-Error "Some combinations were built with errors."
 }
 
 # Display timer statistics to host
@@ -174,16 +178,19 @@ $SolutionsFailed = $jresult.SolutionsFailed
 $Results = $jresult.Results
 
 Write-Output ""
-Write-Output "Built solutions."
-Write-Output ""
-Write-Output "Total elapsed time:   $min minutes, $seconds seconds."
-Write-Output "SolutionsTotal:       $SolutionsTotal"
-Write-Output "SolutionsSucceeded:   $SolutionsSucceeded"
-Write-Output "SolutionsExcluded:    $SolutionsExcluded"
-Write-Output "SolutionsUnsupported: $SolutionsUnsupported"
-Write-Output "SolutionsFailed:      $SolutionsFailed"
+Write-Output "Built all combinations."
 Write-Output ""
-Write-Output "Results saved to $sampleBuilderFilePath"
+Write-Output "Elapsed time:         $min minutes, $seconds seconds."
+Write-Output ("Samples:              "+$sampleSet.Count)
+Write-Output ("Configurations:       "+$Configurations.Count+" ("+$Configurations+")")
+Write-Output ("Platforms:            "+$Platforms.Count+" ("+$Platforms+")")
+Write-Output "Combinations:         $SolutionsTotal"
+Write-Output "Succeeded:            $SolutionsSucceeded"
+Write-Output "Excluded:             $SolutionsExcluded"
+Write-Output "Unsupported:          $SolutionsUnsupported"
+Write-Output "Failed:               $SolutionsFailed"
+Write-Output "Log files directory:  $LogFilesDirectory"
+Write-Output "Overview report:      $sampleBuilderFilePath"
 Write-Output ""
 
 $Results | Sort-Object { $_.Sample } | ConvertTo-Html -Title "Overview" | Out-File $sampleBuilderFilePath

Building-Locally.md

@@ -8,12 +8,16 @@ winget install --id Git.Git --source winget`
 
 ## Step 2: Create a "driver build environment"
 
-There are multiple ways to achieve this. For example, [install Visual Studio and the Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk#download-and-install-the-windows-11-version-22h2-wdk). You can just download and mount the EWDK as well.
+There are multiple ways to achieve this. For example, [install Visual Studio and the Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk#download-and-install-the-windows-11-version-22h2-wdk). 
 
-In the following example that is what we will do:
+You can also just download and mount the EWDK as well and in the following example that is what we will do:
   * Download the Windows 11, version 22H2 EWDK ISO image from the [official site](https://learn.microsoft.com/en-us/legal/windows/hardware/enterprise-wdk-license-2022)
   * Mount ISO image
-  * From a terminal, run `.\LaunchBuildEnv`
+  * Open a terminal
+  * `.\LaunchBuildEnv`
+  * `set PLATFORM=`
+
+Note: The last command to clear the PLATFORM variable is added so as to allow the next part to iterate over all platforms automatically without having to add explicit arguments.
 
 ## Step 3: Clone Windows Driver Samples and checkout main branch
 
@@ -27,12 +31,27 @@ cd Windows-driver-samples
 
 ```
 pwsh
-.\Build-AllSamples.ps1 -Configurations 'Debug','Release' -Platforms 'x64','arm64' -LogFilesDirectory '_logs'
+.\Build-AllSamples
+```
+Above builds all samples for all configurations and archictures.  
+
+You can refine, for example as follows:
+```
+pwsh
+.\Build-AllSamples -Samples 'tools.' -Configurations 'Debug','Release' -Platforms 'x64','arm64' -LogFilesDirectory .\_logs
 ```
 
 Expected output:
 ```
-T: Total solutions: 612
+Samples:              153
+Configurations:       2 (Debug Release)
+Platforms:            2 (x64 arm64)
+Combinations:         612
+Logical Processors:   12
+Throttle factor:      5
+Throttle limit:       60
+
+T: Combinations
 B: Built
 R: Build is running currently
 P: Build is pending an available build slot
@@ -42,16 +61,19 @@ E: Built and result was 'Excluded'
 U: Built and result was 'Unsupported' (Platform and Configuration combination)
 F: Built and result was 'Failed'
 
-Building driver solutions...
+Building all combinations...
 
-Built solutions.
+Built all combinations.
 
-Total elapsed time:   11 minutes, 18 seconds.
-SolutionsTotal:       612
-SolutionsSucceeded:   316
-SolutionsExcluded:    56
-SolutionsUnsupported: 240
-SolutionsFailed:      0
-
-Results saved to _logs\overview.htm
-```
+Elapsed time:         12 minutes, 34 seconds.
+Samples:              153
+Configurations:       2 (Debug Release)
+Platforms:            2 (x64 arm64)
+Combinations:         612
+Succeeded:            326
+Excluded:             56
+Unsupported:          230
+Failed:               0
+Log files directory:  .\_logs
+Overview report:      .\_logs\overview.htm
+```