Skip to content

Commit a7f04ed

Browse files
Copilotrijesha
Copilot
and
rijesha
authored
Add comprehensive GitHub Copilot instructions with expanded repository structure for Zephyr IDE development (#136)
* Initial plan * Create comprehensive .github/copilot-instructions.md Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com> * Expand Repository Structure section with detailed file descriptions and architecture patterns Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com> --------- Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>
1 parent aea1e23 commit a7f04ed

File tree

2 files changed

+276
-2
lines changed

2 files changed

+276
-2
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Zephyr IDE VS Code Extension
2+
3+
**ALWAYS follow these instructions first and only fallback to search or bash commands when encountering unexpected information that does not match the info here.**
4+
5+
Zephyr IDE is a VS Code extension that provides comprehensive tools for Zephyr RTOS development. It includes workspace setup, SDK installation, project creation, building, debugging, and testing capabilities.
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Dependencies
10+
**CRITICAL: All build and test commands take significant time. NEVER CANCEL operations.**
11+
12+
```bash
13+
# Install Node.js dependencies (40 seconds)
14+
npm install
15+
16+
# Install Python west tool for Zephyr development
17+
pip3 install west
18+
19+
# Verify required tools are available
20+
which python3 && python3 --version
21+
which cmake && cmake --version
22+
which west && west --version
23+
which ninja && ninja --version
24+
```
25+
26+
### Build Commands
27+
**Set timeouts to 10+ minutes for all build commands. NEVER CANCEL.**
28+
29+
```bash
30+
# Compile TypeScript (3 seconds)
31+
npm run test-compile
32+
33+
# Compile for development (3 seconds)
34+
npm run compile
35+
36+
# Bundle extension with esbuild (1 second)
37+
npm run esbuild
38+
39+
# Production build with minification (1 second)
40+
npm run vscode:prepublish
41+
42+
# Run ESLint (2 seconds)
43+
npm run lint
44+
45+
# Full pretest pipeline: compile + esbuild + lint (6 seconds)
46+
npm run pretest
47+
```
48+
49+
### Testing Commands
50+
**CRITICAL: Integration tests take 10-15 minutes each. Set timeouts to 20+ minutes. NEVER CANCEL.**
51+
52+
```bash
53+
# Run all tests (requires VS Code download, network-dependent)
54+
# TIMEOUT: 20+ minutes
55+
npm test
56+
57+
# Run specific integration test suites (requires Zephyr SDK)
58+
# TIMEOUT: 15+ minutes each - NEVER CANCEL
59+
xvfb-run -a node scripts/run-integration-tests.js standard
60+
xvfb-run -a node scripts/run-integration-tests.js git
61+
xvfb-run -a node scripts/run-integration-tests.js zephyr-ide-git
62+
xvfb-run -a node scripts/run-integration-tests.js open-current-dir
63+
xvfb-run -a node scripts/run-integration-tests.js out-of-tree
64+
65+
# Skip actual Zephyr builds in tests (faster testing)
66+
SKIP_BUILD_TESTS=true npm test
67+
```
68+
69+
### VS Code Extension Development
70+
```bash
71+
# Open extension for development
72+
# 1. Open VS Code in the repository directory
73+
# 2. Press F5 or Run → Start Debugging
74+
# 3. Select "Run Extension" configuration
75+
# This launches a new VS Code window with the extension loaded for testing
76+
```
77+
78+
## Validation Scenarios
79+
80+
**ALWAYS test these scenarios after making changes to ensure functionality:**
81+
82+
### Manual Extension Validation
83+
1. **Extension Loading**: Press F5 to launch extension host, verify Zephyr IDE appears in activity bar
84+
2. **Workspace Setup**: Test workspace initialization commands work
85+
3. **Project Creation**: Verify project creation from templates functions
86+
4. **Build Configuration**: Test build configuration setup
87+
5. **Command Palette**: Verify all "Zephyr IDE:" commands are available
88+
89+
### Integration Test Coverage
90+
The integration tests validate complete workflows:
91+
- **Standard Workspace**: Dependencies → west setup → SDK install → project creation → build (15 min)
92+
- **Git Workspace**: Git clone → SDK → project → custom board build (15 min)
93+
- **Zephyr IDE Git**: Zephyr IDE specific git workflow (15 min)
94+
- **Open Directory**: Current directory workspace setup (15 min)
95+
- **Out of Tree**: Out-of-tree project builds (15 min)
96+
97+
## Repository Structure
98+
99+
### Core Source Files
100+
```
101+
src/
102+
├── extension.ts - Main extension entry point, registers commands and webview panels
103+
├── defines.ts - Zephyr toolchain targets, HALs, and UI dropdown definitions
104+
├── panels/ - 5 webview panels for different aspects of the UI
105+
│ ├── active_project_view/ - Shows current project build status and controls
106+
│ ├── extension_setup_view/ - Initial workspace setup and SDK installation
107+
│ ├── project_config_view/ - Project-specific configuration (boards, runners, etc.)
108+
│ ├── project_tree_view/ - File explorer for Zephyr projects
109+
│ ├── setup_panel/ - Workspace configuration and tool validation
110+
│ └── view.css - Shared CSS styles for all webview panels
111+
├── project_utilities/ - Project-level operations and configuration
112+
│ ├── build_selector.ts - Board and target selection logic
113+
│ ├── config_selector.ts - Kconfig and devicetree configuration
114+
│ ├── project.ts - Core project management and build operations
115+
│ ├── runner_selector.ts - Flash/debug runner configuration
116+
│ └── twister_selector.ts - Test runner configuration
117+
├── setup_utilities/ - Workspace setup and dependency management
118+
│ ├── dts_interface.ts - Devicetree parsing and intellisense
119+
│ ├── host_tools.ts - Host tool detection and validation
120+
│ ├── modules.ts - Zephyr module management
121+
│ ├── state-management.ts - Extension state persistence
122+
│ ├── tools-validation.ts - Tool version checking and compatibility
123+
│ ├── types.ts - TypeScript type definitions
124+
│ ├── west-operations.ts - West workspace operations
125+
│ ├── west_sdk.ts - Zephyr SDK installation and management
126+
│ ├── west_selector.ts - West manifest selection and configuration
127+
│ ├── workspace-config.ts - Workspace configuration management
128+
│ └── workspace-setup.ts - Initial workspace setup orchestration
129+
├── zephyr_utilities/ - Core Zephyr build system integration
130+
│ ├── build.ts - CMake/Ninja build execution
131+
│ ├── flash.ts - Device flashing and debugging
132+
│ └── twister.ts - Test execution and reporting
133+
├── test/ - Integration test suites (15+ min each)
134+
│ ├── standard-workspace.test.ts - Full workspace setup → build
135+
│ ├── west-git-workspace.test.ts - Git-based workspace creation
136+
│ ├── zephyr-ide-git-workspace.test.ts - Zephyr IDE specific git workflow
137+
│ ├── open-current-directory.test.ts - Current directory workspace
138+
│ ├── workspace-out-of-tree.test.ts - Out-of-tree project builds
139+
│ ├── test-runner.ts - Test execution framework
140+
│ └── ui-mock-interface.ts - Mock UI for headless testing
141+
└── utilities/ - Shared helper functions
142+
├── getNonce.ts - Security nonce generation for webviews
143+
├── multistepQuickPick.ts - Multi-step UI selection workflows
144+
└── utils.ts - General utility functions
145+
```
146+
147+
### Build and Distribution
148+
```
149+
dist/ - Production bundled extension (esbuild output)
150+
out/ - Development compiled TypeScript (tsc output)
151+
scripts/ - Build automation and test runners
152+
west_templates/ - West.yml templates for different workspace types
153+
```
154+
155+
### Configuration Files
156+
```
157+
package.json - Extension manifest, commands, activation events, npm scripts
158+
tsconfig.json - TypeScript compilation settings, path mappings
159+
.eslintrc.json - Code style rules, import organization
160+
.vscode-test.mjs - VS Code test runner configuration, download settings
161+
.vscode/launch.json - F5 debug launch configurations for extension development
162+
.vscodeignore - Files excluded from extension package
163+
```
164+
165+
### Key Architecture Patterns
166+
- **Command Registration**: All VS Code commands defined in `package.json` and registered in `extension.ts`
167+
- **Webview Communication**: Panels use message passing between TypeScript and HTML/JS
168+
- **State Management**: Extension state persisted via VS Code APIs in `state-management.ts`
169+
- **Async Operations**: Long-running builds use VS Code Progress API with cancellation support
170+
- **Error Handling**: Consistent error reporting through VS Code notification APIs
171+
172+
## Common Development Tasks
173+
174+
### Code Changes Workflow
175+
```bash
176+
# 1. Make code changes to src/
177+
# 2. Compile and lint
178+
npm run test-compile
179+
npm run lint
180+
181+
# 3. Test extension
182+
# Press F5 in VS Code to launch extension host
183+
184+
# 4. Run integration tests if needed (NEVER CANCEL - 15+ min each)
185+
SKIP_BUILD_TESTS=true npm test # Quick test
186+
xvfb-run -a node scripts/run-integration-tests.js standard # Full test
187+
```
188+
189+
### Before Committing
190+
**ALWAYS run these commands before committing changes:**
191+
```bash
192+
# Required for CI to pass
193+
npm run lint
194+
npm run test-compile
195+
npm run esbuild
196+
197+
# Recommended full validation
198+
npm run pretest
199+
```
200+
201+
### Extension Packaging
202+
```bash
203+
# Build for production
204+
npm run vscode:prepublish
205+
206+
# Package extension (requires vsce tool)
207+
vsce package
208+
```
209+
210+
## Troubleshooting
211+
212+
### Build Issues
213+
- **TypeScript errors**: Run `npm run compile` to see detailed errors
214+
- **Bundling issues**: Check `npm run esbuild` output
215+
- **Lint failures**: Run `npm run lint` and fix ESLint warnings
216+
217+
### Test Issues
218+
- **VS Code download failures**: Network connectivity issue, retry tests
219+
- **Integration test timeouts**: NEVER CANCEL - tests take 15+ minutes
220+
- **Zephyr build failures**: Install Zephyr SDK and build dependencies
221+
- **Mock UI failures**: Check UI mock interface in test files
222+
223+
### Development Issues
224+
- **Extension not loading**: Check console for errors in extension host
225+
- **Commands not working**: Verify command registration in package.json
226+
- **Webview issues**: Check panel implementations in src/panels/
227+
228+
## CI/CD Integration
229+
230+
The `.github/workflows/integration-tests.yml` runs on:
231+
- Push to main, pre-release, develop branches
232+
- Pull requests to those branches
233+
234+
**CI Requirements:**
235+
- Ubuntu with Zephyr build tools
236+
- 20+ minute timeouts for integration tests
237+
- xvfb for headless VS Code testing
238+
- NEVER CANCEL long-running operations
239+
240+
## Environment Variables
241+
242+
- `SKIP_BUILD_TESTS=true` - Skip actual Zephyr builds in tests
243+
- `NODE_ENV=test` - Test environment configuration
244+
- `ZEPHYR_BASE=/tmp/zephyr` - Zephyr installation base path
245+
- `CI=true` - Automatically detected in CI environments
246+
247+
## Dependencies
248+
249+
### Required for Development
250+
- Node.js 18+ (for npm and extension bundling)
251+
- VS Code (for extension development and testing)
252+
- Git (for version control)
253+
254+
### Required for Full Testing
255+
- Python 3.8+ with pip
256+
- west (`pip3 install west`)
257+
- cmake, ninja-build
258+
- Zephyr SDK (for integration tests)
259+
- xvfb (for headless testing on Linux)
260+
261+
### System Packages (Ubuntu)
262+
```bash
263+
sudo apt-get install python3-pip python3-venv cmake ninja-build gperf \
264+
ccache dfu-util device-tree-compiler wget file make gcc gcc-multilib \
265+
g++-multilib libsdl2-dev libmagic1
266+
```
267+
268+
**TIMING EXPECTATIONS:**
269+
- npm install: ~40 seconds
270+
- TypeScript compilation: ~3 seconds
271+
- ESLint: ~2 seconds
272+
- esbuild bundling: ~1 second
273+
- Integration tests: 15+ minutes each - NEVER CANCEL
274+
- Full CI pipeline: 60+ minutes - NEVER CANCEL

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)