MegaBites-AI/Windows-powershell

1---2applyTo:3  - "**/*.ps1"4  - "**/*.psm1"5---6 7# Using Start-NativeExecution for Native Command Execution8 9## Purpose10 11`Start-NativeExecution` is the standard function for executing native commands (external executables) in PowerShell scripts within this repository. It provides consistent error handling and better diagnostics when native commands fail.12 13## When to Use14 15Use `Start-NativeExecution` whenever you need to:16- Execute external commands (e.g., `git`, `dotnet`, `pkgbuild`, `productbuild`, `fpm`, `rpmbuild`)17- Ensure proper exit code checking18- Get better error messages with caller information19- Handle verbose output on error20 21## Basic Usage22 23```powershell24Start-NativeExecution {25    git clone https://github.com/PowerShell/PowerShell.git26}27```28 29## With Parameters30 31Use backticks for line continuation within the script block:32 33```powershell34Start-NativeExecution {35    pkgbuild --root $pkgRoot `36        --identifier $pkgIdentifier `37        --version $Version `38        --scripts $scriptsDir `39        $outputPath40}41```42 43## Common Parameters44 45### -VerboseOutputOnError46 47Captures command output and displays it only if the command fails:48 49```powershell50Start-NativeExecution -VerboseOutputOnError {51    dotnet build --configuration Release52}53```54 55### -IgnoreExitcode56 57Allows the command to fail without throwing an exception:58 59```powershell60Start-NativeExecution -IgnoreExitcode {61    git diff --exit-code  # Returns 1 if differences exist62}63```64 65## Availability66 67The function is defined in `tools/buildCommon/startNativeExecution.ps1` and is available in:68- `build.psm1` (dot-sourced automatically)69- `tools/packaging/packaging.psm1` (dot-sourced automatically)70- Test modules that include `HelpersCommon.psm1`71 72To use in other scripts, dot-source the function:73 74```powershell75. "$PSScriptRoot/../buildCommon/startNativeExecution.ps1"76```77 78## Error Handling79 80When a native command fails (non-zero exit code), `Start-NativeExecution`:811. Captures the exit code822. Identifies the calling location (file and line number)833. Throws a descriptive error with full context84 85Example error message:86```87Execution of {git clone ...} by /path/to/script.ps1: line 42 failed with exit code 188```89 90## Examples from the Codebase91 92### Git Operations93```powershell94Start-NativeExecution {95    git fetch --tags --quiet upstream96}97```98 99### Build Operations100```powershell101Start-NativeExecution -VerboseOutputOnError {102    dotnet publish --configuration Release103}104```105 106### Packaging Operations107```powershell108Start-NativeExecution -VerboseOutputOnError {109    pkgbuild --root $pkgRoot --identifier $pkgId --version $version $outputPath110}111```112 113### Permission Changes114```powershell115Start-NativeExecution {116    find $staging -type d | xargs chmod 755117    find $staging -type f | xargs chmod 644118}119```120 121## Anti-Patterns122 123**Don't do this:**124```powershell125& somecommand $args126if ($LASTEXITCODE -ne 0) {127    throw "Command failed"128}129```130 131**Do this instead:**132```powershell133Start-NativeExecution {134    somecommand $args135}136```137 138## Best Practices139 1401. **Always use Start-NativeExecution** for native commands to ensure consistent error handling1412. **Use -VerboseOutputOnError** for commands with useful diagnostic output1423. **Use backticks for readability** when commands have multiple arguments1434. **Don't capture output unnecessarily** - let the function handle it1445. **Use -IgnoreExitcode sparingly** - only when non-zero exit codes are expected and acceptable145 146## Related Documentation147 148- Source: `tools/buildCommon/startNativeExecution.ps1`149- Blog post: https://mnaoumov.wordpress.com/2015/01/11/execution-of-external-commands-in-powershell-done-right/150