MegaBites-AI/Windows-powershell

1---2applyTo:3  - "build.psm1"4  - "tools/ci.psm1"5  - ".github/**/*.yml"6  - ".github/**/*.yaml"7  - ".pipelines/**/*.yml"8---9 10# Build Configuration Guide11 12## Choosing the Right Configuration13 14### For Testing15 16**Use: Default (Debug)**17 18```yaml19- name: Build for Testing20  shell: pwsh21  run: |22    Import-Module ./tools/ci.psm123    Start-PSBuild24```25 26**Why Debug:**27- Includes debugging symbols28- Better error messages29- Faster build times30- Suitable for xUnit and Pester tests31 32**Do NOT use:**33- `-Configuration 'Release'` (unnecessary for tests)34- `-ReleaseTag` (not needed for tests)35- `-CI` (unless you specifically need Pester module)36 37### For Release/Packaging38 39**Use: Release with version tag and public NuGet feeds**40 41```yaml42- name: Build for Release43  shell: pwsh44  run: |45    Import-Module ./build.psm146    Import-Module ./tools/ci.psm147    Switch-PSNugetConfig -Source Public48    $releaseTag = Get-ReleaseTag49    Start-PSBuild -Configuration 'Release' -ReleaseTag $releaseTag50```51 52**Why Release:**53- Optimized binaries54- No debug symbols (smaller size)55- Production-ready56 57**Why Switch-PSNugetConfig -Source Public:**58- Switches NuGet package sources to public feeds (nuget.org and public Azure DevOps feeds)59- Required for CI/CD environments that don't have access to private feeds60- Uses publicly available packages instead of Microsoft internal feeds61 62### For Code Coverage63 64**Use: CodeCoverage configuration**65 66```yaml67- name: Build with Coverage68  shell: pwsh69  run: |70    Import-Module ./tools/ci.psm171    Start-PSBuild -Configuration 'CodeCoverage'72```73 74## Platform Considerations75 76### All Platforms77 78Same commands work across Linux, Windows, and macOS:79 80```yaml81strategy:82  matrix:83    os: [ubuntu-latest, windows-latest, macos-latest]84runs-on: ${{ matrix.os }}85steps:86  - name: Build PowerShell87    shell: pwsh88    run: |89      Import-Module ./tools/ci.psm190      Start-PSBuild91```92 93### Output Locations94 95**Linux/macOS:**96```97src/powershell-unix/bin/Debug/<netversion>/<runtime>/publish/98```99 100**Windows:**101```102src/powershell-win-core/bin/Debug/<netversion>/<runtime>/publish/103```104 105## Best Practices106 1071. Use default configuration for testing1082. Avoid redundant parameters1093. Match configuration to purpose1104. Use `-CI` only when needed1115. Always specify `-ReleaseTag` for release or packaging builds1126. Use `Switch-PSNugetConfig -Source Public` in CI/CD for release builds113 114## NuGet Feed Configuration115 116### Switch-PSNugetConfig117 118The `Switch-PSNugetConfig` function in `build.psm1` manages NuGet package source configuration.119 120**Available Sources:**121 122- **Public**: Uses public feeds (nuget.org and public Azure DevOps feeds)123  - Required for: CI/CD environments, public builds, packaging124  - Does not require authentication125 126- **Private**: Uses internal PowerShell team feeds127  - Required for: Internal development with preview packages128  - Requires authentication credentials129 130- **NuGetOnly**: Uses only nuget.org131  - Required for: Minimal dependency scenarios132 133**Usage:**134 135```powershell136# Switch to public feeds (most common for CI/CD)137Switch-PSNugetConfig -Source Public138 139# Switch to private feeds with authentication140Switch-PSNugetConfig -Source Private -UserName $userName -ClearTextPAT $pat141 142# Switch to nuget.org only143Switch-PSNugetConfig -Source NuGetOnly144```145 146**When to Use:**147 148- **Always use `-Source Public`** before building in CI/CD workflows149- Use before any build that will create packages for distribution150- Use in forks or environments without access to Microsoft internal feeds151