[CmdletBinding()]

param(

[string]$Configuration = "Debug",

[ValidateSet('x64')]

[string]$Platform = "x64",

[switch]$Serial,

[switch]$BuildTests,

[switch]$RunTests,

[string]$TestFilter,

[switch]$BuildAdditionalApps,

[string]$Project = "FieldWorks.proj",

[string]$Verbosity = "minimal",

[ValidateSet('true', 'false', 'auto')]

[string]$NodeReuse = 'auto',

[string[]]$MsBuildArgs = @(),

[string]$LogFile,

[int]$TailLines,

[switch]$SkipRestore,

[switch]$SkipNative,

[switch]$SkipNativeTests,

[switch]$ForceBuildBuildTasks,

[switch]$BuildInstaller,

[switch]$BuildPatch,

[ValidateSet('Wix3', 'Wix6')]

[string]$InstallerToolset = "Wix3",

[switch]$InstallerOnly,

[switch]$ForceInstallerOnly,

[switch]$SignInstaller,

[switch]$TraceCrashes,

[switch]$UseLocalLcm,

[string]$LocalLcmPath,

[ValidateSet('user', 'agent', 'unknown')]

[string]$StartedBy = 'unknown',

[switch]$SkipWorktreeLock,

[switch]$SkipDependencyCheck

)

$ErrorActionPreference = "Stop"

if (-not $PSBoundParameters.ContainsKey('StartedBy') -and -not [string]::IsNullOrWhiteSpace($env:FW_BUILD_STARTED_BY)) {

$startedByFromEnv = $env:FW_BUILD_STARTED_BY.ToLowerInvariant()

if ($startedByFromEnv -in @('user', 'agent', 'unknown')) {

$StartedBy = $startedByFromEnv

}

}

$env:PATH = "$env:WIX/bin;$env:PATH"

if ($Configuration -like "--*") {

if ($Configuration -eq "--TraceCrashes" -and -not $TraceCrashes) {

$TraceCrashes = $true

$Configuration = "Debug"

Write-Output "[WARN] Detected '--TraceCrashes' passed without PowerShell switch parsing. Using -TraceCrashes and defaulting Configuration to Debug."

}

else {

throw "Invalid Configuration value '$Configuration'. Use -TraceCrashes (single dash) for the trace option."

}

}

if ($BuildInstaller -and -not $BuildAdditionalApps) {

$BuildAdditionalApps = $true

Write-Host "BuildInstaller enabled: including additional apps (use -BuildAdditionalApps:$false to skip)." -ForegroundColor Yellow

}

if (($BuildInstaller -or $BuildPatch) -and -not ($Configuration -eq "Release")) {

$Configuration = "Release"

Write-Host "Installer builds must be Release builds; changing Configuration to Release" -ForegroundColor Yellow

}

$isGitHubActions = ($env:GITHUB_ACTIONS -eq 'true')

if ($Configuration -eq 'Release' -and -not $isGitHubActions) {

$buildNumberOk = $false

if (-not [string]::IsNullOrWhiteSpace($env:FW_BUILD_NUMBER)) {

$parsedBuildNumber = 0

if ([int]::TryParse($env:FW_BUILD_NUMBER, [ref]$parsedBuildNumber) -and $parsedBuildNumber -ge 0 -and $parsedBuildNumber -le 65535) {

$buildNumberOk = $true

}

}

if (-not $buildNumberOk) {

$utcNow = (Get-Date).ToUniversalTime()

$env:FW_BUILD_NUMBER = "{0}{1:000}" -f $utcNow.ToString('yy'), $utcNow.DayOfYear

Write-Host "Using local numeric build number: $($env:FW_BUILD_NUMBER)" -ForegroundColor Yellow

}

if ([string]::IsNullOrWhiteSpace($env:FW_BUILD_LABEL)) {

$env:FW_BUILD_LABEL = "local_{0}" -f (Get-Date).ToUniversalTime().ToString('yyyyMMdd')

Write-Host "Using local build label: $($env:FW_BUILD_LABEL)" -ForegroundColor Yellow

}

}

$helpersPath = Join-Path $PSScriptRoot "Build/Agent/FwBuildHelpers.psm1"

if (-not (Test-Path $helpersPath)) {

Write-Host "[ERROR] FwBuildHelpers.psm1 not found at $helpersPath" -ForegroundColor Red

exit 1

}

Import-Module $helpersPath -Force

$worktreeLock = $null

$cleanupArgs = @{

IncludeOmniSharp = $true

RepoRoot = $PSScriptRoot

}

$testExitCode = 0

function Get-RepoStamp {

$gitHead = & git rev-parse HEAD

if ($LASTEXITCODE -ne 0) {

throw "Failed to determine git HEAD (git rev-parse HEAD)."

}

$gitHead = ($gitHead | Out-String).Trim()

$gitStatus = & git status --porcelain

if ($LASTEXITCODE -ne 0) {

throw "Failed to determine git dirty state (git status --porcelain)."

}

$gitStatusText = ($gitStatus | Out-String)

$isDirty = -not [string]::IsNullOrWhiteSpace($gitStatusText)

# For installer-only iteration, allow local edits under FLExInstaller/** while still blocking

# when *product* inputs have changed (e.g. Src/**).

$isDirtyOutsideInstaller = $false

if ($isDirty) {

$lines = @()

foreach ($line in ($gitStatusText -split "`r?`n")) {

$trimmed = $line.TrimEnd()

if ([string]::IsNullOrWhiteSpace($trimmed)) {

continue

}

$lines += $trimmed

}

foreach ($statusLine in $lines) {

if ($statusLine.Length -lt 4) {

continue

}

# Porcelain format: XY<space>PATH (or XY<space>OLD -> NEW)

$pathPart = $statusLine.Substring(3).Trim()

if ($pathPart -like "* -> *") {

$pathPart = ($pathPart.Split(@(" -> "), 2, [System.StringSplitOptions]::None)[1]).Trim()

}

if (-not ($pathPart -like "FLExInstaller/*")) {

$isDirtyOutsideInstaller = $true

break

}

}

}

return [pscustomobject]@{

GitHead = $gitHead

IsDirty = $isDirty

IsDirtyOutsideInstaller = $isDirtyOutsideInstaller

}

}

function Get-BuildStampPath {

param(

[Parameter(Mandatory = $true)][string]$RepoRoot,

[Parameter(Mandatory = $true)][string]$ConfigurationName

)

$outputDir = Join-Path $RepoRoot ("Output\\{0}" -f $ConfigurationName)

return Join-Path $outputDir "BuildStamp.json"

}

function Resolve-NodeReuse {

param(

[Parameter(Mandatory = $true)][string]$Mode

)

$normalizedMode = $Mode.ToLowerInvariant()

if ($normalizedMode -eq 'true') {

return [pscustomobject]@{

Enabled = $true

Source = 'explicit'

Reason = 'requested explicitly'

}

}

if ($normalizedMode -eq 'false') {

return [pscustomobject]@{

Enabled = $false

Source = 'explicit'

Reason = 'requested explicitly'

}

}

$worktreeList = & git worktree list --porcelain

if ($LASTEXITCODE -ne 0) {

Write-Warning 'Failed to inspect git worktrees. Defaulting MSBuild node reuse to false for safety.'

return [pscustomobject]@{

Enabled = $false

Source = 'auto'

Reason = 'git worktree detection failed'

}

}

$worktreeCount = 0

foreach ($line in (($worktreeList | Out-String) -split "`r?`n")) {

if ($line.StartsWith('worktree ')) {

$worktreeCount++

}

}

if ($worktreeCount -le 1) {

return [pscustomobject]@{

Enabled = $true

Source = 'auto'

Reason = 'single local worktree detected'

}

}

return [pscustomobject]@{

Enabled = $false

Source = 'auto'

Reason = "$worktreeCount local worktrees detected"

}

}

try {

if (-not $SkipWorktreeLock) {

$worktreeLock = Enter-WorktreeLock -RepoRoot $PSScriptRoot -Context "FieldWorks build" -StartedBy $StartedBy

}

# Worktree-aware cleanup: only stop conflicting processes related to this repo root.

Stop-ConflictingProcesses -IncludeOmniSharp -RepoRoot $PSScriptRoot

$fwTasksSourcePath = Join-Path $PSScriptRoot "BuildTools/FwBuildTasks/$Configuration/FwBuildTasks.dll"

$fwTasksDropPath = Join-Path $PSScriptRoot "BuildTools/FwBuildTasks/$Configuration/FwBuildTasks.dll"

Invoke-WithFileLockRetry -Context "FieldWorks build" -IncludeOmniSharp -RepoRoot $PSScriptRoot -Action {

# Initialize Visual Studio Developer environment

Initialize-VsDevEnvironment

Test-CvtresCompatibility

if (-not $SkipDependencyCheck) {

$verifyScript = Join-Path $PSScriptRoot "Build/Agent/Verify-FwDependencies.ps1"

if (Test-Path $verifyScript) {

Write-Host "Running dependency preflight..." -ForegroundColor Cyan

& $verifyScript -FailOnMissing

if ($LASTEXITCODE -ne 0) {

throw "Dependency preflight failed. Re-run with -SkipDependencyCheck only if you are actively debugging environment setup."

}

}

}

# Set architecture environment variable (x64-only)

$env:arch = 'x64'

Write-Host "Set arch environment variable to: $env:arch" -ForegroundColor Green

# Stop conflicting processes before the build

Stop-ConflictingProcesses @cleanupArgs

$projectPath = $Project

$rootedProjectPath = Join-Path $PSScriptRoot $Project

if (-not (Test-Path $projectPath) -and (Test-Path $rootedProjectPath)) {

$projectPath = $rootedProjectPath

}

if (-not (Test-Path $projectPath)) {

throw "Project path '$Project' was not found. Pass a path relative to the repo root or an absolute path."

}

# Clean stale per-project obj/ folders

Remove-StaleObjFolders -RepoRoot $PSScriptRoot

# LT-22382: Remove stale first-party DLLs from the output directory before building.

# Uses a whitelist of assembly names from Src/**/*.csproj to identify FW assemblies

# and checks their major version against FWMAJOR. See Build\Agent\Remove-StaleDlls.ps1.

$staleDllScript = Join-Path $PSScriptRoot "Build\Agent\Remove-StaleDlls.ps1"

if (Test-Path $staleDllScript) {

$outputDir = "Output\$Configuration"

& $staleDllScript -OutputDir $outputDir -RepoRoot $PSScriptRoot -Verbose:$VerbosePreference

}

# =============================================================================

# Build Configuration

# =============================================================================

# Determine logical core count for CL_MPCount

if ($env:CL_MPCount) {

$mpCount = $env:CL_MPCount

}

else {

$mpCount = 8

if ($env:NUMBER_OF_PROCESSORS) {

$procCount = [int]$env:NUMBER_OF_PROCESSORS

if ($procCount -lt 8) { $mpCount = $procCount }

}

}

# Construct MSBuild arguments

$finalMsBuildArgs = @()

$nodeReuseDecision = Resolve-NodeReuse -Mode $NodeReuse

# Parallelism

if (-not $Serial) {

$finalMsBuildArgs += "/m"

}

# Verbosity & Logging

$finalMsBuildArgs += "/v:$Verbosity"

$finalMsBuildArgs += "/nologo"

$finalMsBuildArgs += "/consoleloggerparameters:Summary"

# Node Reuse

$finalMsBuildArgs += "/nr:$($nodeReuseDecision.Enabled.ToString().ToLower())"

# Properties

$finalMsBuildArgs += "/p:Configuration=$Configuration"

$finalMsBuildArgs += "/p:Platform=$Platform"

if ($SkipNative) {

$finalMsBuildArgs += "/p:SkipNative=true"

}

$installerMsBuildArgs = $finalMsBuildArgs

# Args specific to the main build (not the installer)

if ($TraceCrashes) {

$finalMsBuildArgs += "/p:UseDevTraceConfig=true"

}

$finalMsBuildArgs += "/p:CL_MPCount=$mpCount"

if ($env:FW_TRACE_LOG) {

$finalMsBuildArgs += "/p:FW_TRACE_LOG=`"$($env:FW_TRACE_LOG)`""

}

if ($BuildTests -or $RunTests) {

$finalMsBuildArgs += "/p:BuildTests=true"

$finalMsBuildArgs += "/p:BuildNativeTests=true"

}

if ($BuildAdditionalApps) {

$finalMsBuildArgs += "/p:BuildAdditionalApps=true"

}

# Add user-supplied args

$finalMsBuildArgs += $MsBuildArgs

$installerMsBuildArgs += $MsBuildArgs

# =============================================================================

# Build Execution

# =============================================================================

Write-Host ""

Write-Host "Building FieldWorks..." -ForegroundColor Cyan

Write-Host "Project: $projectPath" -ForegroundColor Cyan

Write-Host "Configuration: $Configuration | Platform: $Platform | Parallel: $(-not $Serial) | Tests: $($BuildTests -or $RunTests) | NodeReuse: $($nodeReuseDecision.Enabled) [$($nodeReuseDecision.Source): $($nodeReuseDecision.Reason)]" -ForegroundColor Cyan

if ($BuildAdditionalApps) {

Write-Host "Including optional FieldWorks executables" -ForegroundColor Yellow

}

# Report local library packages when LOCAL_NUGET_REPO is configured

if ($env:LOCAL_NUGET_REPO -and (Test-Path $env:LOCAL_NUGET_REPO)) {

$localPkgs = Get-ChildItem -Path $env:LOCAL_NUGET_REPO -Filter "SIL.*.nupkg" -File -ErrorAction SilentlyContinue

if ($localPkgs.Count -gt 0) {

Write-Host ""

Write-Host "Local library packages detected in $($env:LOCAL_NUGET_REPO):" -ForegroundColor Yellow

foreach ($pkg in $localPkgs) {

Write-Host " $($pkg.Name)" -ForegroundColor Yellow

}

Write-Host "These will shadow upstream NuGet packages during restore." -ForegroundColor Yellow

Write-Host ""

}

}

# Bootstrap: Build FwBuildTasks first (required by SetupInclude.targets)

if (-not (Test-Path $fwTasksSourcePath) -or $ForceBuildBuildTasks) {

$fwBuildTasksOutputDir = Join-Path $PSScriptRoot "BuildTools/FwBuildTasks/$Configuration/"

Invoke-MSBuild `

-Arguments @('Build/Src/FwBuildTasks/FwBuildTasks.csproj', '/t:Restore;Build', "/p:Configuration=$Configuration", "/p:Platform=$Platform", `

"/p:FwBuildTasksOutputPath=$fwBuildTasksOutputDir", "/p:SkipFwBuildTasksAssemblyCheck=true", "/p:SkipFwBuildTasksUsingTask=true", "/p:SkipGenerateFwTargets=true", `

"/p:SkipSetupTargets=true", "/v:quiet", "/nologo") `

-Description 'FwBuildTasks (Bootstrap)'

}

if (-not (Test-Path $fwTasksSourcePath)) {

throw "Failed to build FwBuildTasks. Expected $fwTasksSourcePath to exist."

}

if ($fwTasksSourcePath -ne $fwTasksDropPath) {

$dropDir = Split-Path $fwTasksDropPath -Parent

if (-not (Test-Path $dropDir)) {

New-Item -Path $dropDir -ItemType Directory -Force | Out-Null

}

Copy-Item -Path $fwTasksSourcePath -Destination $fwTasksDropPath -Force

}

# Restore packages

if (-not $SkipRestore) {

Write-Host "Restoring NuGet packages..." -ForegroundColor Cyan

$packagesDir = Join-Path $PSScriptRoot "packages"

if (-not (Test-Path $packagesDir)) {

New-Item -Path $packagesDir -ItemType Directory -Force | Out-Null

}

& dotnet restore "$PSScriptRoot\FieldWorks.sln" /p:NoWarn=NU1903 /p:DisableWarnForInvalidRestoreProjects=true "/p:Configuration=$Configuration" "/p:Platform=$Platform" --verbosity quiet

if ($LASTEXITCODE -ne 0) {

throw "NuGet package restore failed for FieldWorks.sln"

}

Write-Host "Package restore complete." -ForegroundColor Green

} else {

Write-Host "Skipping package restore (-SkipRestore)" -ForegroundColor Yellow

}

# Copy local LCM assemblies if requested

if ($UseLocalLcm) {

Write-Host ""

Write-Host "Applying local LCM assemblies..." -ForegroundColor Cyan

$lcmCopyScript = Join-Path $PSScriptRoot "scripts\Agent\Copy-LocalLcm.ps1"

$lcmArgs = @{

Configuration = $Configuration

BuildLcm = $true

SkipConfirm = $true

}

if ($LocalLcmPath) {

$lcmArgs['LcmRoot'] = $LocalLcmPath

}

& $lcmCopyScript @lcmArgs

if ($LASTEXITCODE -ne 0) {

throw "Failed to copy local LCM assemblies."

}

}

if ($InstallerOnly) {

if (-not $BuildInstaller -and -not $BuildPatch) {

throw "-InstallerOnly requires -BuildInstaller or -BuildPatch."

}

$stampPath = Get-BuildStampPath -RepoRoot $PSScriptRoot -ConfigurationName $Configuration

if (-not (Test-Path $stampPath)) {

throw "-InstallerOnly requested but no build stamp was found at '$stampPath'. Run a full build once (without -InstallerOnly) to create it."

}

$stamp = Get-Content -LiteralPath $stampPath -Raw | ConvertFrom-Json

$current = Get-RepoStamp

$stampConfig = $stamp.Configuration

$stampPlatform = $stamp.Platform

if (($stampConfig -ne $Configuration) -or ($stampPlatform -ne $Platform)) {

throw "-InstallerOnly stamp mismatch: stamp is Configuration='$stampConfig' Platform='$stampPlatform' but this run is Configuration='$Configuration' Platform='$Platform'. Run a full build in this configuration/platform."

}

$headChanged = ($stamp.GitHead -ne $current.GitHead)

if ((-not $ForceInstallerOnly) -and ($headChanged -or $current.IsDirtyOutsideInstaller)) {

throw "-InstallerOnly refused: product inputs may have changed since the last full build stamp. Run a full build, or use -ForceInstallerOnly if you are sure Output\\$Configuration is still correct."

}

Write-Host ""

Write-Host "Skipping product build (-InstallerOnly). Reusing Output\\$Configuration." -ForegroundColor Yellow

}

else {

# Build using traversal project

Invoke-MSBuild `

-Arguments (@($projectPath) + $finalMsBuildArgs) `

-Description "FieldWorks Solution" `

-LogPath $LogFile `

-TailLines $TailLines

# Avoid log file collisions between the main build and the installer build.

if (Test-Path "msbuild.binlog") {

Rename-Item -Path "msbuild.binlog" -NewName "msbuild-FieldWorks.binlog" -Force

}

$stampDir = Join-Path $PSScriptRoot ("Output\\{0}" -f $Configuration)

if (-not (Test-Path $stampDir)) {

New-Item -Path $stampDir -ItemType Directory -Force | Out-Null

}

$repoStamp = Get-RepoStamp

$stampObject = [pscustomobject]@{

Configuration = $Configuration

Platform = $Platform

GitHead = $repoStamp.GitHead

IsDirty = $repoStamp.IsDirty

IsDirtyOutsideInstaller = $repoStamp.IsDirtyOutsideInstaller

TimestampUtc = (Get-Date).ToUniversalTime().ToString('o')

}

$stampPath = Get-BuildStampPath -RepoRoot $PSScriptRoot -ConfigurationName $Configuration

$stampObject | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath $stampPath -Encoding UTF8

Write-Host ""

Write-Host "[OK] Build complete!" -ForegroundColor Green

Write-Host "Output: Output\$Configuration" -ForegroundColor Cyan

}

if ($BuildInstaller -or $BuildPatch) {

if ($BuildPatch) {

$BaseOrPatch = "Patch"

}

else {

$BaseOrPatch = "Installer"

}

Write-Host ""

Write-Host "Building $BaseOrPatch..." -ForegroundColor Cyan

# Use a different LogFile name than the main build to avoid collisions.

if (-not [string]::IsNullOrWhiteSpace($LogFile)) {

$LogFileExtension = [System.IO.Path]::GetExtension($LogFile)

$LogFile = [System.IO.Path]::ChangeExtension($LogFile, "$BaseOrPatch$LogFileExtension")

}

if (-not $isGitHubActions) {

if ($SignInstaller) {

Write-Host "Signing enabled for local installer build." -ForegroundColor Yellow

$env:FILESTOSIGNLATER = $null

}

else {

$defaultSignList = Join-Path $PSScriptRoot "Output\files-to-sign.txt"

if ([string]::IsNullOrWhiteSpace($env:FILESTOSIGNLATER)) {

$env:FILESTOSIGNLATER = $defaultSignList

}

Write-Host "Signing disabled for local build; capturing files to $env:FILESTOSIGNLATER" -ForegroundColor Yellow

}

}

$installerCleanArg = "/p:InstallerCleanProductOutputs=false"

if ($isGitHubActions) {

$installerCleanArg = "/p:InstallerCleanProductOutputs=true"

}

Invoke-MSBuild `

-Arguments (@('Build/InstallerBuild.proj', "/t:Build$BaseOrPatch", '/p:config=release', "/p:InstallerToolset=$InstallerToolset", $installerCleanArg) + `

$InstallerMsBuildArgs) `

-Description "$BaseOrPatch Build" `

-LogPath $LogFile `

-TailLines $TailLines

# Avoid log file collisions between the main build and the installer build.

if (Test-Path "msbuild.binlog") {

Rename-Item -Path "msbuild.binlog" -NewName "msbuild-$BaseOrPatch.binlog" -Force

}

Write-Host "[OK] $BaseOrPatch build complete!" -ForegroundColor Green

}

}

# =============================================================================

# Test Execution (Optional)

# =============================================================================

if ($RunTests) {

Write-Host ""

Write-Host "Running tests..." -ForegroundColor Cyan

$testArgs = @{

Configuration = $Configuration

NoBuild = $true

Verbosity = $Verbosity

SkipDependencyCheck = $SkipDependencyCheck

SkipWorktreeLock = $true

}

if ($TestFilter) {

$testArgs["TestFilter"] = $TestFilter

}

if ($SkipNative -or $SkipNativeTests) {

$testArgs["SkipNative"] = $true

}

Stop-ConflictingProcesses @cleanupArgs

& "$PSScriptRoot\test.ps1" @testArgs

$script:testExitCode = $LASTEXITCODE

if ($script:testExitCode -eq 1) {

# VSTest exit code 1 means tests were skipped (or skipped+failed). test.ps1 prints a

# FAIL summary when there are actual failures, so treat exit code 1 as a warning only

# to avoid failing the build when the only non-passing tests were skipped.

Write-Warning "Test run exited with code 1 (skipped tests or failures). Check test output above for details."

$script:testExitCode = 0

} elseif ($script:testExitCode -ne 0) {

Write-Warning "Some tests failed (exit code: $($script:testExitCode)). Check output above for details."

}

}

}

finally {

# Kill any lingering build processes that might hold file locks

Stop-ConflictingProcesses @cleanupArgs

if ($worktreeLock) {

Exit-WorktreeLock -LockHandle $worktreeLock

}

}

if ($testExitCode -ne 0) {

exit $testExitCode

}