@samitouri / QOSAMI-WSL-1 / commits / 3794ba34

Add comprehensive GitHub Copilot instructions for WSL development (#13352)

* Initial plan * Add comprehensive GitHub Copilot instructions for WSL repository Co-authored-by: benhillis <17727402+benhillis@users.noreply.github.com> * Address reviewer feedback: fix build commands and test parameters Co-authored-by: benhillis <17727402+benhillis@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: benhillis <17727402+benhillis@users.noreply.github.com>

Copilot committed Aug 7, 2025 at 17:24 UTC 3794ba34968e621e4bb493dfba312b2c4571e537
1 file changed +218
.github/copilot-instructions.md new
+218
@@ -0,0 +1,218 @@
1 +# Windows Subsystem for Linux (WSL)
2 +
3 +**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
4 +
5 +WSL is the Windows Subsystem for Linux - a compatibility layer for running Linux binary executables natively on Windows. This repository contains the core Windows components that enable WSL functionality.
6 +
7 +## Working Effectively
8 +
9 +### Critical Platform Requirements
10 +- **Full builds ONLY work on Windows** with Visual Studio and Windows SDK 26100
11 +- **DO NOT attempt to build the main WSL components on Linux** - they require Windows-specific APIs, MSBuild, and Visual Studio toolchain
12 +- Many validation and development tasks CAN be performed on Linux (documentation, formatting, Python validation scripts)
13 +
14 +### Windows Build Requirements (Required for Full Development)
15 +- CMake >= 3.25 (`winget install Kitware.CMake`)
16 +- Visual Studio with these components:
17 + - Windows SDK 26100
18 + - MSBuild
19 + - Universal Windows platform support for v143 build tools (X64 and ARM64)
20 + - MSVC v143 - VS 2022 C++ ARM64 build tools (Latest + Spectre) (X64 and ARM64)
21 + - C++ core features
22 + - C++ ATL for latest v143 tools (X64 and ARM64)
23 + - C++ Clang compiler for Windows
24 + - .NET desktop development
25 + - .NET WinUI app development tools
26 +- Enable Developer Mode in Windows Settings OR run with Administrator privileges (required for symbolic link support)
27 +
28 +### Building WSL (Windows Only)
29 +1. Clone the repository
30 +2. Generate Visual Studio solution: `cmake .`
31 +3. Build: `cmake --build . -- -m` OR open `wsl.sln` in Visual Studio
32 +4. **NEVER CANCEL: Build takes 20-45 minutes on typical hardware. Set timeout to 60+ minutes.**
33 +
34 +Build parameters:
35 +- `cmake . -A arm64` - Build for ARM64
36 +- `cmake . -DCMAKE_BUILD_TYPE=Release` - Release build
37 +- `cmake . -DBUILD_BUNDLE=TRUE` - Build bundle msix package (requires ARM64 built first)
38 +
39 +### Deploying WSL (Windows Only)
40 +- Install MSI: `bin\<platform>\<target>\wsl.msi`
41 +- OR use script: `powershell tools\deploy\deploy-to-host.ps1`
42 +- For Hyper-V VM: `powershell tools\deploy\deploy-to-vm.ps1 -VmName <vm> -Username <user> -Password <pass>`
43 +
44 +## Cross-Platform Development Tasks
45 +
46 +### Documentation (Works on Linux/Windows)
47 +- Install tools: `pip install mkdocs-mermaid2-plugin mkdocs --break-system-packages`
48 +- Build docs: `mkdocs build -f doc/mkdocs.yml`
49 +- **Build time: ~0.5 seconds. Set timeout to 5+ minutes for safety.**
50 +- Output location: `doc/site/`
51 +- **Note**: May show warnings about mermaid CDN access on restricted networks
52 +
53 +### Code Formatting and Validation (Works on Linux/Windows)
54 +- Format check: `clang-format --dry-run --style=file <files>`
55 +- Apply formatting: `clang-format -i --style=file <files>`
56 +- Format all source: `powershell formatsource.ps1` (available at repo root after running `cmake .`)
57 +- Validate copyright headers: `python3 tools/devops/validate-copyright-headers.py`
58 + - **Note**: Will report missing headers in generated/dependency files (_deps/), which is expected
59 +- Validate localization: `python3 tools/devops/validate-localization.py`
60 + - **Note**: Only works after Windows build (requires localization/strings/en-us/Resources.resw)
61 +
62 +### Distribution Validation (Limited on Linux)
63 +- Validate distribution info: `python3 distributions/validate.py distributions/DistributionInfo.json`
64 +- **Note**: May fail on Linux due to network restrictions accessing distribution URLs
65 +
66 +## Testing
67 +
68 +### Unit Tests (Windows Only - TAEF Framework)
69 +- Run all tests: `bin\<platform>\<target>\test.bat`
70 +- **NEVER CANCEL: Full test suite takes 30-60 minutes. Set timeout to 90+ minutes.**
71 +- Run subset: `bin\<platform>\<target>\test.bat /name:*UnitTest*`
72 +- Run specific test: `bin\<platform>\<target>\test.bat /name:<class>::<test>`
73 +- WSL1 tests: Add `-Version 1` flag
74 +- Fast mode (after first run): Add `-f` flag (requires `wsl --set-default test_distro`)
75 +
76 +Test debugging:
77 +- Wait for debugger: `/waitfordebugger`
78 +- Break on failure: `/breakonfailure`
79 +- Run in-process: `/inproc`
80 +
81 +### Linux Unit Tests (Linux Only)
82 +- Location: `test/linux/unit_tests/`
83 +- Build script: `test/linux/unit_tests/build_tests.sh`
84 +- **Note**: Requires specific Linux build environment setup not covered in main build process
85 +
86 +## Validation Scenarios
87 +
88 +### Always Test These After Changes:
89 +1. **Documentation Build**: Run `mkdocs build -f doc/mkdocs.yml` and verify no errors
90 +2. **Code Formatting**: Run `clang-format --dry-run --style=file` on changed files
91 +3. **Windows Build** (if on Windows): Full cmake build cycle
92 +4. **Distribution Validation**: Run Python validation scripts on any distribution changes
93 +
94 +### Manual Validation Requirements
95 +- **Windows builds**: Install MSI and test basic WSL functionality (`wsl --version`, `wsl -l`)
96 +- **Documentation changes**: Review generated HTML in `doc/site/`
97 +- **Distribution changes**: Test with actual WSL distribution installation
98 +
99 +## Repository Navigation
100 +
101 +### Key Directories
102 +- `src/windows/` - Main Windows WSL service components
103 +- `src/linux/` - Linux-side WSL components
104 +- `src/shared/` - Shared code between Windows and Linux
105 +- `test/windows/` - Windows-based tests (TAEF framework)
106 +- `test/linux/unit_tests/` - Linux unit test suite
107 +- `doc/` - Documentation source (MkDocs)
108 +- `tools/` - Build and deployment scripts
109 +- `distributions/` - Distribution validation and metadata
110 +
111 +### Key Files
112 +- `CMakeLists.txt` - Main build configuration
113 +- `doc/docs/dev-loop.md` - Developer build instructions
114 +- `test/README.md` - Testing framework documentation
115 +- `CONTRIBUTING.md` - Contribution guidelines
116 +- `.clang-format` - Code formatting rules
117 +- `UserConfig.cmake.sample` - Optional build customizations
118 +
119 +### Frequently Used Commands (Platform-Specific)
120 +
121 +#### Windows Development:
122 +```bash
123 +# Initial setup
124 +cmake .
125 +cmake --build . -- -m # 20-45 minutes, NEVER CANCEL
126 +
127 +# Deploy and test
128 +powershell tools\deploy\deploy-to-host.ps1
129 +wsl --version
130 +
131 +# Run tests
132 +bin\x64\debug\test.bat # 30-60 minutes, NEVER CANCEL
133 +```
134 +
135 +#### Cross-Platform Validation:
136 +```bash
137 +# Documentation (0.5 seconds)
138 +mkdocs build -f doc/mkdocs.yml
139 +
140 +# Code formatting
141 +find src -name "*.cpp" -o -name "*.h" | xargs clang-format --dry-run --style=file
142 +
143 +# Copyright header validation (reports expected issues in _deps/)
144 +python3 tools/devops/validate-copyright-headers.py
145 +
146 +# Distribution validation (may fail on networks without external access)
147 +python3 distributions/validate.py distributions/DistributionInfo.json
148 +```
149 +
150 +## Debugging and Logging
151 +
152 +### ETL Tracing (Windows Only)
153 +```powershell
154 +# Collect traces
155 +wpr -start diagnostics\wsl.wprp -filemode
156 +# [reproduce issue]
157 +wpr -stop logs.ETL
158 +```
159 +
160 +### Log Analysis Tools
161 +- Use WPA (Windows Performance Analyzer) for ETL traces
162 +- Key providers: `Microsoft.Windows.Lxss.Manager`, `Microsoft.Windows.Subsystem.Lxss`
163 +
164 +### Debug Console (Linux)
165 +Add to `%USERPROFILE%\.wslconfig`:
166 +```ini
167 +[wsl2]
168 +debugConsole=true
169 +```
170 +
171 +### Common Debugging Commands
172 +- Debug shell: `wsl --debug-shell`
173 +- Collect WSL logs: `powershell diagnostics\collect-wsl-logs.ps1`
174 +- Network logs: `powershell diagnostics\collect-networking-logs.ps1`
175 +
176 +## Critical Timing and Timeout Guidelines
177 +
178 +**NEVER CANCEL these operations - always wait for completion:**
179 +
180 +- **Full Windows build**: 20-45 minutes (set timeout: 60+ minutes)
181 +- **Full test suite**: 30-60 minutes (set timeout: 90+ minutes)
182 +- **Unit test subset**: 5-15 minutes (set timeout: 30+ minutes)
183 +- **Documentation build**: ~0.5 seconds (set timeout: 5+ minutes)
184 +- **Distribution validation**: 2-5 minutes (set timeout: 15+ minutes)
185 +
186 +## CI/CD Integration
187 +
188 +### GitHub Actions
189 +- **distributions.yml**: Validates distribution metadata (Linux)
190 +- **documentation.yml**: Builds and deploys docs (Linux)
191 +- **modern-distributions.yml**: Tests modern distribution support
192 +
193 +### Pre-commit Validation
194 +Always run before committing:
195 +1. `clang-format --dry-run --style=file` on changed C++ files
196 +2. `python3 tools/devops/validate-copyright-headers.py` (ignore _deps/ warnings)
197 +3. `mkdocs build -f doc/mkdocs.yml` if documentation changed
198 +4. Full Windows build if core components changed
199 +
200 +**Note**: The `.gitignore` file properly excludes build artifacts (*.sln, *.dll, *.pdb, obj/, bin/, etc.) - do not commit these files.
201 +
202 +## Development Environment Setup
203 +
204 +### Windows (Full Development)
205 +1. Install Visual Studio with required components (listed above)
206 +2. Install CMake 3.25+
207 +3. Enable Developer Mode
208 +4. Clone repository
209 +5. Run `cmake .` to generate solution
210 +
211 +### Linux (Documentation/Validation Only)
212 +1. Install Python 3.8+
213 +2. Install clang-format
214 +3. Install docs tools: `pip install mkdocs-mermaid2-plugin mkdocs`
215 +4. Clone repository
216 +5. Run validation commands as needed
217 +
218 +Remember: **This is a Windows-focused project**. While some tasks can be performed on Linux, full WSL development requires Windows with Visual Studio.
\ No newline at end of file