Mirrors/PowerToys
1
0
Fork 0
mirror of https://github.com/microsoft/PowerToys.git synced 2025-12-16 11:48:06 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
fix-peek-ui-tests-#42254
PowerToys/tools/build/BUILD-GUIDELINES.md
Gordon Lam 05ae867ac8 Enable just build in any cmd or powershell simply (not necessary in Developer Command Prompt for VS 2022) (#41475) 
This pull request refactors and modernizes the PowerToys build scripts
to provide a more robust, platform-aware, and user-friendly local build
experience. The changes introduce shared PowerShell helpers, add clear
documentation, improve Visual Studio environment detection, and unify
build logic across scripts. The new approach enables easier builds from
any folder, better error reporting, and automatic platform detection for
x64/arm64.

**Build system modernization and shared helpers:**

* Added new shared helper script `build-common.ps1` containing reusable
functions for MSBuild invocation, Visual Studio environment
initialization, project discovery, and platform auto-detection. This
script is now dot-sourced by all build scripts for consistent behavior.
* Refactored `build-essentials.ps1` and `build-installer.ps1` to use the
shared helpers, enabling automatic Visual Studio dev environment setup
and platform detection. Both scripts now work from any folder inside the
repo and provide improved logging and error handling.
[[1]](diffhunk://#diff-946ed85e16779fdbcfeb7de80f631eae2da0f7bd478e27e22621121b409dde88L1-R73)
[[2]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L55-R77)

**Improved build workflow and error reporting:**

* All build scripts now write detailed logs (full, errors, warnings,
binlog) next to the solution/project being built, with troubleshooting
guidance documented in the new guidelines.
[[1]](diffhunk://#diff-43764921d6c830dbb3a15fe875aebfbc46966ae5ff62f3179adb3ff046b47b9dR1-R284)
[[2]](diffhunk://#diff-283bc775aac55085b6a0a47e40b3cf619fff47e20a2f5537fd6dd342d19d2afdR1-R48)
* Command-line wrappers (`build.cmd`, `build-essentials.cmd`) added for
easy invocation from `cmd.exe`, forwarding all arguments to the
PowerShell scripts.
[[1]](diffhunk://#diff-4bf353f2a88f1378983e4e2f3a5555e69b6a6ccfbe004001c1ebfe99ca57903dR1-R5)
[[2]](diffhunk://#diff-48b3da077cd89d8ed6befe57a781bea813e6f9594bfcefbc320b20dea589c5abR1-R6)

**Documentation and usage guidance:**

* Introduced `BUILD-GUIDELINES.md` with clear instructions, usage
examples, and troubleshooting tips for all build scripts, including
platform overrides and log locations.

**Installer pipeline improvements:**

* The installer build pipeline (`build-installer.ps1`) now uses shared
helpers for platform detection and Visual Studio initialization, and
passes unified build arguments to all MSBuild invocations, improving
consistency and maintainability.
[[1]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L83-L126)
[[2]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L137-R113)
[[3]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L151-R128)
[[4]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L162-R142)

---

**References:**  

[[1]](diffhunk://#diff-43764921d6c830dbb3a15fe875aebfbc46966ae5ff62f3179adb3ff046b47b9dR1-R284)
[[2]](diffhunk://#diff-946ed85e16779fdbcfeb7de80f631eae2da0f7bd478e27e22621121b409dde88L1-R73)
[[3]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L55-R77)
[[4]](diffhunk://#diff-283bc775aac55085b6a0a47e40b3cf619fff47e20a2f5537fd6dd342d19d2afdR1-R48)
[[5]](diffhunk://#diff-4bf353f2a88f1378983e4e2f3a5555e69b6a6ccfbe004001c1ebfe99ca57903dR1-R5)
[[6]](diffhunk://#diff-48b3da077cd89d8ed6befe57a781bea813e6f9594bfcefbc320b20dea589c5abR1-R6)
[[7]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L83-L126)
[[8]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L137-R113)
[[9]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L151-R128)
[[10]](diffhunk://#diff-21888769485d767c43c0895fe315e6f6d7384da62f60ef917d8a61a610da10b9L162-R142)
2025-09-01 10:23:27 +08:00

2.5 KiB
Raw Permalink Blame History

Build scripts – quick guideline

Use these scripts to build PowerToys locally. They auto-detect your platform (x64/arm64), initialize the Visual Studio developer environment, and write helpful logs on failure.

Quick start (from cmd.exe)

  • Fast essentials (runner + settings) and NuGet restore first:
    • tools\build\build-essentials.cmd
  • Build projects in the current folder:
    • tools\build\build.cmd

Tip: Add D:\PowerToys\tools\build to your PATH to use the wrappers anywhere.

When to use which

  1. build-essentials.ps1

    • Restores NuGet for PowerToys.sln and builds essentials (runner, settings).
    • Auto-detects Platform; initializes VS Dev environment automatically.
    • Example (PowerShell):
      • ./tools/build/build-essentials.ps1
      • ./tools/build/build-essentials.ps1 -Platform arm64 -Configuration Release

  2. build.ps1 (from any folder)

    • Builds any .sln/.csproj/.vcxproj in the current directory.
    • Auto-detects Platform; initializes VS Dev environment automatically.
    • Accepts extra MSBuild args (forwarded to msbuild):
      • ./tools/build/build.ps1 '/p:CIBuild=true' '/p:SomeProp=Value'
    • Restore only:
      • ./tools/build/build.ps1 -RestoreOnly

  3. build-installer.ps1 (use with caution)

    • Full local packaging pipeline (restore, build, sign MSIX, WiX v5 MSI/bootstrapper).
    • Auto-inits VS Dev environment. Cleans some output (keeps *.exe) under installer/.
    • Key options: -PerUser true|false, -InstallerSuffix wix5|vnext.
    • Example:
      • ./tools/build/build-installer.ps1 -Platform x64 -Configuration Release -PerUser true -InstallerSuffix wix5

Logs and troubleshooting

  • On failure, see logs next to the solution/project being built:
    • build.<configuration>.<platform>.all.log — full text log
    • build.<configuration>.<platform>.errors.log — errors only
    • build.<configuration>.<platform>.warnings.log — warnings only
    • build.<configuration>.<platform>.trace.binlog — open with MSBuild Structured Log Viewer
  • VS environment init:
    • Scripts try DevShell first (Microsoft.VisualStudio.DevShell.dll / Enter-VsDevShell), then fall back to VsDevCmd.bat.
    • If VS isn’t found, run from “Developer PowerShell for VS 2022”, or ensure vswhere.exe exists under Program Files (x86)\Microsoft Visual Studio\Installer.

Notes

  • Override platform explicitly with -Platform x64|arm64 if needed.
  • CMD wrappers: build.cmd, build-essentials.cmd forward all arguments to the PowerShell scripts.
Reference in New Issue View Git Blame Copy Permalink