From ca95cb5eeb3c113b46c7f9a6fbd9d45c68b0bfcd Mon Sep 17 00:00:00 2001 From: JakobL-MSFT <110699333+JakobL-MSFT@users.noreply.github.com> Date: Thu, 18 Apr 2024 17:33:50 -0700 Subject: [PATCH] NuGet notes (#1120) * NuGet notes * Update Building-Locally.md * Update Building-Locally.md: Update instructions for usb\usbview sample * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md * Update Building-Locally.md --- Building-Locally.md | 193 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 166 insertions(+), 27 deletions(-) diff --git a/Building-Locally.md b/Building-Locally.md index 77f747a03..114a5ed32 100644 --- a/Building-Locally.md +++ b/Building-Locally.md @@ -1,23 +1,58 @@ # How to build locally -## Step 1: Install Git and PowerShell 7 +## Step 1: Install Tools ``` winget install --id Microsoft.Powershell --source winget winget install --id Git.Git --source winget ``` -## Step 2: Create a "driver build environment" +For using WDK NuGet feed based build additionally: +``` +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 +``` + +## Step 3: Optional: Install Microsoft .NET Framework 4.7.2 Targeting Pack and Microsoft .NET Framework 4.8.1 SDK + +When: This step is only required to build sample usb\usbview . + +### 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 -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). +### Option B: Use EWDK +Easy: If you use EWDK, then all necessary prequisites are included. -You can also use the Enterprise WDK (EWDK), a standalone, self-contained command-line environment for building drivers: - * 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 - * Open a terminal - * `.\LaunchBuildEnv` - -## Step 3: Clone Windows Driver Samples and checkout main branch +### 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 3: Clone Windows Driver Samples and checkout relevant branch ``` cd path\to\your\repos @@ -25,7 +60,59 @@ git clone --recurse-submodules https://github.com/microsoft/Windows-driver-sampl cd Windows-driver-samples ``` -## Step 4: Check all samples builds with expected results for all flavors +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: +``` +git checkout develop +``` + +## Step 4: Create a "driver build environment" + +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 +* Note: This option is only available in pre-release form. +* 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. +* Install the Visual Studio Windows Driver Kit Extension (WDK.vsix). Open Visual Studio -> Extensions -> Manage Extensions... -> Online -> Visual Studio Market Place -> Windows Driver Kit -> 10.0.26090.10 -> Download +* Launch a "Developer Command Prompt for VS 2022". +* Restore WDK packages from feed : + +``` +>cd path\to\your\repos\Windows-driver-samples +>nuget restore -PackagesDirectory .\packages +``` + +* When this is done you should have a .\packages folder that looks exactly as follows: +``` +>cd path\to\your\repos\Windows-driver-samples +>dir /b packages +Microsoft.Windows.SDK.CPP.10.0.26095.2-preview.ge-release +Microsoft.Windows.SDK.CPP.x64.10.0.26095.2-preview.ge-release +Microsoft.Windows.SDK.CPP.arm64.10.0.26095.2-preview.ge-release +Microsoft.Windows.WDK.x64.10.0.26095.2-preview.ge-release +Microsoft.Windows.WDK.arm64.10.0.26095.2-preview.ge-release +``` +### 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. +* 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 +* Open a terminal +* `.\LaunchBuildEnv` + + +## Step 5: Check all samples builds with expected results for all flavors ``` pwsh @@ -33,21 +120,42 @@ pwsh ``` Above builds all samples for all configurations and platforms. -You can refine, for example as follows: +You can refine what exact samples to build, what configurations, and platforms to build. build Here are a few examples: ``` -pwsh +# Get Help: +Get-Help .\Build-AllSamples + +# Build all solutions for all flavors with builds running in parallel: +.\Build-AllSamples + +# Build with Verbose output (print start and finish of each sample): +.\Build-AllSamples -Verbose + +# Build without massive parallism (slow, but good debugging): +.\Build-AllSamples -ThrottleLimit 1 + +# Build the solutions in the tools folder for all flavors: .\Build-AllSamples -Samples '^tools.' -Configurations 'Debug','Release' -Platforms 'x64','arm64' + +# Build the solutions in the tools folder for only 'Debug|x64': +.\Build-AllSamples -Samples '^tools.' -Configurations 'Debug' -Platforms 'x64' ``` Expected output: ``` -Samples: 153 -Configurations: 2 (Debug Release) -Platforms: 2 (x64 arm64) -Combinations: 612 -Logical Processors: 12 -Throttle factor: 5 -Throttle limit: 60 +PS > .\build-AllSamples.ps1 +Build Environment: NuGet +Build Number: 26095 +Samples: 132 +Configurations: 2 (Debug Release) +Platforms: 2 (x64 arm64) +InfVerif_AdditionalOptions: /samples +Combinations: 528 +LogicalProcessors: 12 +ThrottleFactor: 5 +ThrottleLimit: 60 +WDS_WipeOutputs: +Disk Remaining (GB): ... T: Combinations B: Built @@ -58,20 +166,51 @@ S: Built and result was 'Succeeded' E: Built and result was 'Excluded' U: Built and result was 'Unsupported' (Platform and Configuration combination) F: Built and result was 'Failed' +O: Built and result was 'Sporadic' Building all combinations... Built all combinations. -Elapsed time: 12 minutes, 34 seconds. -Samples: 153 +Elapsed time: 12 minutes, 42 seconds. +Disk Remaining (GB): ... +Samples: 132 Configurations: 2 (Debug Release) Platforms: 2 (x64 arm64) -Combinations: 612 -Succeeded: 326 -Excluded: 56 -Unsupported: 230 +Combinations: 528 +Succeeded: 526 +Excluded: 0 +Unsupported: 2 Failed: 0 +Sporadic: 0 Log files directory: .\_logs -Overview report: .\_logs\_overview.htm +Overview report: .\_overview.htm +``` + +# NuGet - Additional Notes + +To restore a specific version of our WDK NuGet packages: + +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-SampleSet and change the NuGet build number (used by .\exclusions.csv and for determining infverif flags) +* Now you can run "nuget restore" + +A few examples of how to interact with nuget: +``` +# To add an alternative online NuGet source: +nuget sources add -Name "MyNuGetFeed" -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 + +# To remove an alternative NuGet source: +nuget sources remove -Name "MyNuGetFeed" + +# To enumerate NuGet locals: +nuget locals all -list + +# To clear NuGet locals: +nuget locals all -clear ```