diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..4ff6e45 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,218 @@ +# Windows Subsystem for Linux (WSL) + +**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.** + +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. + +## Working Effectively + +### Critical Platform Requirements +- **Full builds ONLY work on Windows** with Visual Studio and Windows SDK 26100 +- **DO NOT attempt to build the main WSL components on Linux** - they require Windows-specific APIs, MSBuild, and Visual Studio toolchain +- Many validation and development tasks CAN be performed on Linux (documentation, formatting, Python validation scripts) + +### Windows Build Requirements (Required for Full Development) +- CMake >= 3.25 (`winget install Kitware.CMake`) +- Visual Studio with these components: + - Windows SDK 26100 + - MSBuild + - Universal Windows platform support for v143 build tools (X64 and ARM64) + - MSVC v143 - VS 2022 C++ ARM64 build tools (Latest + Spectre) (X64 and ARM64) + - C++ core features + - C++ ATL for latest v143 tools (X64 and ARM64) + - C++ Clang compiler for Windows + - .NET desktop development + - .NET WinUI app development tools +- Enable Developer Mode in Windows Settings OR run with Administrator privileges (required for symbolic link support) + +### Building WSL (Windows Only) +1. Clone the repository +2. Generate Visual Studio solution: `cmake .` +3. Build: `cmake --build . -- -m` OR open `wsl.sln` in Visual Studio +4. **NEVER CANCEL: Build takes 20-45 minutes on typical hardware. Set timeout to 60+ minutes.** + +Build parameters: +- `cmake . -A arm64` - Build for ARM64 +- `cmake . -DCMAKE_BUILD_TYPE=Release` - Release build +- `cmake . -DBUILD_BUNDLE=TRUE` - Build bundle msix package (requires ARM64 built first) + +### Deploying WSL (Windows Only) +- Install MSI: `bin\\\wsl.msi` +- OR use script: `powershell tools\deploy\deploy-to-host.ps1` +- For Hyper-V VM: `powershell tools\deploy\deploy-to-vm.ps1 -VmName -Username -Password ` + +## Cross-Platform Development Tasks + +### Documentation (Works on Linux/Windows) +- Install tools: `pip install mkdocs-mermaid2-plugin mkdocs --break-system-packages` +- Build docs: `mkdocs build -f doc/mkdocs.yml` +- **Build time: ~0.5 seconds. Set timeout to 5+ minutes for safety.** +- Output location: `doc/site/` +- **Note**: May show warnings about mermaid CDN access on restricted networks + +### Code Formatting and Validation (Works on Linux/Windows) +- Format check: `clang-format --dry-run --style=file ` +- Apply formatting: `clang-format -i --style=file ` +- Format all source: `powershell formatsource.ps1` (available at repo root after running `cmake .`) +- Validate copyright headers: `python3 tools/devops/validate-copyright-headers.py` + - **Note**: Will report missing headers in generated/dependency files (_deps/), which is expected +- Validate localization: `python3 tools/devops/validate-localization.py` + - **Note**: Only works after Windows build (requires localization/strings/en-us/Resources.resw) + +### Distribution Validation (Limited on Linux) +- Validate distribution info: `python3 distributions/validate.py distributions/DistributionInfo.json` +- **Note**: May fail on Linux due to network restrictions accessing distribution URLs + +## Testing + +### Unit Tests (Windows Only - TAEF Framework) +- Run all tests: `bin\\\test.bat` +- **NEVER CANCEL: Full test suite takes 30-60 minutes. Set timeout to 90+ minutes.** +- Run subset: `bin\\\test.bat /name:*UnitTest*` +- Run specific test: `bin\\\test.bat /name:::` +- WSL1 tests: Add `-Version 1` flag +- Fast mode (after first run): Add `-f` flag (requires `wsl --set-default test_distro`) + +Test debugging: +- Wait for debugger: `/waitfordebugger` +- Break on failure: `/breakonfailure` +- Run in-process: `/inproc` + +### Linux Unit Tests (Linux Only) +- Location: `test/linux/unit_tests/` +- Build script: `test/linux/unit_tests/build_tests.sh` +- **Note**: Requires specific Linux build environment setup not covered in main build process + +## Validation Scenarios + +### Always Test These After Changes: +1. **Documentation Build**: Run `mkdocs build -f doc/mkdocs.yml` and verify no errors +2. **Code Formatting**: Run `clang-format --dry-run --style=file` on changed files +3. **Windows Build** (if on Windows): Full cmake build cycle +4. **Distribution Validation**: Run Python validation scripts on any distribution changes + +### Manual Validation Requirements +- **Windows builds**: Install MSI and test basic WSL functionality (`wsl --version`, `wsl -l`) +- **Documentation changes**: Review generated HTML in `doc/site/` +- **Distribution changes**: Test with actual WSL distribution installation + +## Repository Navigation + +### Key Directories +- `src/windows/` - Main Windows WSL service components +- `src/linux/` - Linux-side WSL components +- `src/shared/` - Shared code between Windows and Linux +- `test/windows/` - Windows-based tests (TAEF framework) +- `test/linux/unit_tests/` - Linux unit test suite +- `doc/` - Documentation source (MkDocs) +- `tools/` - Build and deployment scripts +- `distributions/` - Distribution validation and metadata + +### Key Files +- `CMakeLists.txt` - Main build configuration +- `doc/docs/dev-loop.md` - Developer build instructions +- `test/README.md` - Testing framework documentation +- `CONTRIBUTING.md` - Contribution guidelines +- `.clang-format` - Code formatting rules +- `UserConfig.cmake.sample` - Optional build customizations + +### Frequently Used Commands (Platform-Specific) + +#### Windows Development: +```bash +# Initial setup +cmake . +cmake --build . -- -m # 20-45 minutes, NEVER CANCEL + +# Deploy and test +powershell tools\deploy\deploy-to-host.ps1 +wsl --version + +# Run tests +bin\x64\debug\test.bat # 30-60 minutes, NEVER CANCEL +``` + +#### Cross-Platform Validation: +```bash +# Documentation (0.5 seconds) +mkdocs build -f doc/mkdocs.yml + +# Code formatting +find src -name "*.cpp" -o -name "*.h" | xargs clang-format --dry-run --style=file + +# Copyright header validation (reports expected issues in _deps/) +python3 tools/devops/validate-copyright-headers.py + +# Distribution validation (may fail on networks without external access) +python3 distributions/validate.py distributions/DistributionInfo.json +``` + +## Debugging and Logging + +### ETL Tracing (Windows Only) +```powershell +# Collect traces +wpr -start diagnostics\wsl.wprp -filemode +# [reproduce issue] +wpr -stop logs.ETL +``` + +### Log Analysis Tools +- Use WPA (Windows Performance Analyzer) for ETL traces +- Key providers: `Microsoft.Windows.Lxss.Manager`, `Microsoft.Windows.Subsystem.Lxss` + +### Debug Console (Linux) +Add to `%USERPROFILE%\.wslconfig`: +```ini +[wsl2] +debugConsole=true +``` + +### Common Debugging Commands +- Debug shell: `wsl --debug-shell` +- Collect WSL logs: `powershell diagnostics\collect-wsl-logs.ps1` +- Network logs: `powershell diagnostics\collect-networking-logs.ps1` + +## Critical Timing and Timeout Guidelines + +**NEVER CANCEL these operations - always wait for completion:** + +- **Full Windows build**: 20-45 minutes (set timeout: 60+ minutes) +- **Full test suite**: 30-60 minutes (set timeout: 90+ minutes) +- **Unit test subset**: 5-15 minutes (set timeout: 30+ minutes) +- **Documentation build**: ~0.5 seconds (set timeout: 5+ minutes) +- **Distribution validation**: 2-5 minutes (set timeout: 15+ minutes) + +## CI/CD Integration + +### GitHub Actions +- **distributions.yml**: Validates distribution metadata (Linux) +- **documentation.yml**: Builds and deploys docs (Linux) +- **modern-distributions.yml**: Tests modern distribution support + +### Pre-commit Validation +Always run before committing: +1. `clang-format --dry-run --style=file` on changed C++ files +2. `python3 tools/devops/validate-copyright-headers.py` (ignore _deps/ warnings) +3. `mkdocs build -f doc/mkdocs.yml` if documentation changed +4. Full Windows build if core components changed + +**Note**: The `.gitignore` file properly excludes build artifacts (*.sln, *.dll, *.pdb, obj/, bin/, etc.) - do not commit these files. + +## Development Environment Setup + +### Windows (Full Development) +1. Install Visual Studio with required components (listed above) +2. Install CMake 3.25+ +3. Enable Developer Mode +4. Clone repository +5. Run `cmake .` to generate solution + +### Linux (Documentation/Validation Only) +1. Install Python 3.8+ +2. Install clang-format +3. Install docs tools: `pip install mkdocs-mermaid2-plugin mkdocs` +4. Clone repository +5. Run validation commands as needed + +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