From 7b19b4c21922b9ced9b6542b60c5b1d4821d4887 Mon Sep 17 00:00:00 2001
From: Clint Rutkas <clint@rutkas.com>
Date: Mon, 29 Jun 2026 14:29:14 -0700
Subject: [PATCH] Add build-time guard for Windows long path support (#49028)

PowerToys has deeply nested source paths that exceed the legacy
260-character MAX_PATH limit. Contributors who haven't enabled Windows
long path support hit cryptic 'path too long' / 'could not find file'
errors during their first build.

Add an EnsureLongPathsEnabled MSBuild target in Directory.Build.targets
that reads
HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled and
fails fast with an actionable error (PTLONGPATH) pointing at
tools\build\setup-dev-environment.ps1. Covers both Visual Studio and the
command-line build scripts, skips design-time builds, and can be
bypassed with /p:SkipLongPathsCheck=true.

**What happens if Long file path isn't enabled.**
<img width="824" height="916" alt="image"
src="https://github.com/user-attachments/assets/30731f65-4011-48c0-94b9-e521b4c7d266"
/>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 Directory.Build.targets | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Directory.Build.targets b/Directory.Build.targets
index 4ba887527a..6ad39ac215 100644
--- a/Directory.Build.targets
+++ b/Directory.Build.targets
@@ -4,6 +4,29 @@
   <Import Project="$(MSBuildCachePackageRoot)\build\$(MSBuildCachePackageName).targets" Condition="'$(MSBuildCacheEnabled)' == 'true'" />
   <Import Project="$(MSBuildCacheSharedCompilationPackageRoot)\build\Microsoft.MSBuildCache.SharedCompilation.targets" Condition="'$(MSBuildCacheEnabled)' == 'true'" />
 
+  <!--
+    Onboarding guard: PowerToys has deeply nested source paths that exceed the legacy
+    260-character MAX_PATH limit. Without Windows long path support enabled, the build
+    fails with cryptic "path too long" / "could not find file" errors that are hard for
+    new contributors to diagnose. Detect the missing registry setting up front and emit a
+    clear, actionable error before the confusing failures occur.
+
+    - Covers both Visual Studio (Ctrl+Shift+B) and the command-line build scripts.
+    - Runs only during real builds (skips design-time/IntelliSense passes).
+    - Bypass with /p:SkipLongPathsCheck=true if you know what you're doing.
+    See tools\build\setup-dev-environment.ps1 to enable everything automatically.
+  -->
+  <Target Name="EnsureLongPathsEnabled"
+          BeforeTargets="PrepareForBuild"
+          Condition="'$(DesignTimeBuild)' != 'true' and '$(SkipLongPathsCheck)' != 'true' and '$(OS)' == 'Windows_NT'">
+    <PropertyGroup>
+      <_LongPathsEnabled>$([MSBuild]::GetRegistryValueFromView('HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem', 'LongPathsEnabled', null, RegistryView.Registry64))</_LongPathsEnabled>
+    </PropertyGroup>
+    <Error Condition="'$(_LongPathsEnabled)' != '1'"
+           Code="PTLONGPATH"
+           Text="Windows long path support is not enabled. PowerToys source paths exceed the 260-character MAX_PATH limit, so the build will fail with cryptic 'path too long' errors. Fix it by running (from an elevated PowerShell): .\tools\build\setup-dev-environment.ps1 -- or set HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled = 1 (DWORD) and restart Windows. To bypass this check, build with /p:SkipLongPathsCheck=true." />
+  </Target>
+
   <!-- Override ManifestTool to the x64 host tool under WindowsSdkDir for all projects once the SDK path is known. -->
   <PropertyGroup Label="ManifestToolOverride">
     <ManifestTool Condition="Exists('$(WindowsSdkDir)bin\x64\mt.exe')">$(WindowsSdkDir)bin\x64\mt.exe</ManifestTool>