Copilot instructions

1---
2applyTo:
3  - "**/*.ps1"
4  - "**/*.psm1"
5---
6 
7# Using Start-NativeExecution for Native Command Execution
8 
9## Purpose
10 
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 Use
14 
15Use `Start-NativeExecution` whenever you need to:
16- Execute external commands (e.g., `git`, `dotnet`, `pkgbuild`, `productbuild`, `fpm`, `rpmbuild`)
17- Ensure proper exit code checking
18- Get better error messages with caller information
19- Handle verbose output on error
20 
21## Basic Usage
22 
23```powershell
24Start-NativeExecution {
25    git clone https://github.com/PowerShell/PowerShell.git
26}
27```
28 
29## With Parameters
30 
31Use backticks for line continuation within the script block:
32 
33```powershell
34Start-NativeExecution {
35    pkgbuild --root $pkgRoot `
36        --identifier $pkgIdentifier `
37        --version $Version `
38        --scripts $scriptsDir `
39        $outputPath
40}
41```
42 
43## Common Parameters
44 
45### -VerboseOutputOnError
46 
47Captures command output and displays it only if the command fails:
48 
49```powershell
50Start-NativeExecution -VerboseOutputOnError {
51    dotnet build --configuration Release
52}
53```
54 
55### -IgnoreExitcode
56 
57Allows the command to fail without throwing an exception:
58 
59```powershell
60Start-NativeExecution -IgnoreExitcode {
61    git diff --exit-code  # Returns 1 if differences exist
62}
63```
64 
65## Availability
66 
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```powershell
75. "$PSScriptRoot/../buildCommon/startNativeExecution.ps1"
76```
77 
78## Error Handling
79 
80When a native command fails (non-zero exit code), `Start-NativeExecution`:
811. Captures the exit code
822. Identifies the calling location (file and line number)
833. Throws a descriptive error with full context
84 
85Example error message:
86```
87Execution of {git clone ...} by /path/to/script.ps1: line 42 failed with exit code 1
88```
89 
90## Examples from the Codebase
91 
92### Git Operations
93```powershell
94Start-NativeExecution {
95    git fetch --tags --quiet upstream
96}
97```
98 
99### Build Operations
100```powershell
101Start-NativeExecution -VerboseOutputOnError {
102    dotnet publish --configuration Release
103}
104```
105 
106### Packaging Operations
107```powershell
108Start-NativeExecution -VerboseOutputOnError {
109    pkgbuild --root $pkgRoot --identifier $pkgId --version $version $outputPath
110}
111```
112 
113### Permission Changes
114```powershell
115Start-NativeExecution {
116    find $staging -type d | xargs chmod 755
117    find $staging -type f | xargs chmod 644
118}
119```
120 
121## Anti-Patterns
122 
123**Don't do this:**
124```powershell
125& somecommand $args
126if ($LASTEXITCODE -ne 0) {
127    throw "Command failed"
128}
129```
130 
131**Do this instead:**
132```powershell
133Start-NativeExecution {
134    somecommand $args
135}
136```
137 
138## Best Practices
139 
1401. **Always use Start-NativeExecution** for native commands to ensure consistent error handling
1412. **Use -VerboseOutputOnError** for commands with useful diagnostic output
1423. **Use backticks for readability** when commands have multiple arguments
1434. **Don't capture output unnecessarily** - let the function handle it
1445. **Use -IgnoreExitcode sparingly** - only when non-zero exit codes are expected and acceptable
145 
146## Related Documentation
147 
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