# Development Setup

This guide helps developers set up a development environment for contributing to CppLab IDE.

## Prerequisites

### Required Software

**Python 3.13+**:
```powershell
# Check version
python --version

# Should output: Python 3.13.0 or higher
```

**Download**: https://www.python.org/downloads/

**Installation**: ☑ Add Python to PATH

**pip** (usually included):
```powershell
pip --version
```

### Optional Tools

**Git** (for version control):
```powershell
git --version
```
Download: https://git-scm.com/

**VS Code** (recommended IDE):
- Download: https://code.visualstudio.com/
- Extensions:
  - Python (Microsoft)
  - Pylance (Microsoft)
  - Python Debugger (Microsoft)

**Qt Designer** (for UI editing):
```powershell
pip install pyqt6-tools
```

## Initial Setup

### 1. Clone Repository

```powershell
# Clone from GitHub
git clone https://github.com/yourusername/CppLabEngine.git
cd CppLabEngine
```

### 2. Create Virtual Environment

**Why?** Isolate dependencies from system Python

```powershell
# Create venv
python -m venv venv

# Activate (Windows)
.\venv\Scripts\activate

# Activate (Linux/macOS)
source venv/bin/activate

# Your prompt should change to show (venv)
```

**Deactivate** (when done):
```powershell
deactivate
```

### 3. Install Dependencies

**From requirements.txt**:
```powershell
pip install -r requirements.txt
```

**Contents of requirements.txt**:
```
PyQt6==6.6.1
PyQt6-Qt6==6.6.1
PyQt6-sip==13.6.0
```

**Verify Installation**:
```powershell
pip list

# Should show:
# PyQt6         6.6.1
# PyQt6-Qt6     6.6.1
# PyQt6-sip     13.6.0
```

### 4. Verify MinGW Toolchains

**Check compilers directory**:
```powershell
ls compilers\

# Should show:
# mingw32/
# mingw64/
```

**Test mingw64**:
```powershell
.\compilers\mingw64\bin\g++ --version

# Should output:
# g++ (MinGW-W64 ...) 8.1.0
```

**Test mingw32**:
```powershell
.\compilers\mingw32\bin\g++ --version

# Should output:
# g++ (MinGW.org ...) 8.1.0
```

### 5. Run from Source

```powershell
# Activate venv (if not already)
.\venv\Scripts\activate

# Run application
python -m src.cpplab

# Alternative
python src/cpplab/__main__.py
```

**Expected**: CppLab IDE window opens

## Project Structure

```
CppLabEngine/
├── src/                        ← Source code
│   └── cpplab/
│       ├── __init__.py
│       ├── __main__.py         ← Entry point
│       ├── app.py              ← MainWindow class
│       ├── settings.py         ← Settings management
│       ├── settings_dialog.py  ← Settings UI
│       ├── editor.py           ← Code editor
│       ├── builder.py          ← Build system
│       ├── toolchains.py       ← Toolchain management
│       └── ui/
│           └── MainWindow.ui   ← Qt Designer UI
├── compilers/                  ← MinGW toolchains
│   ├── mingw32/
│   └── mingw64/
├── tests/                      ← Test suite (future)
├── docs/                       ← Documentation
│   └── wiki/                   ← GitHub wiki
├── requirements.txt            ← Python dependencies
├── README.md
├── LICENSE
├── CHANGELOG.md
└── .gitignore
```

## Development Workflow

### Making Changes

**1. Create Feature Branch**:
```powershell
git checkout -b feature/my-feature
```

**2. Make Changes**:
```powershell
# Edit files in src/cpplab/
code src/cpplab/app.py
```

**3. Test Changes**:
```powershell
# Run from source
python -m src.cpplab

# Test manually (build, run, etc.)
```

**4. Commit Changes**:
```powershell
git add .
git commit -m "Add feature: my feature"
```

**5. Push to GitHub**:
```powershell
git push origin feature/my-feature
```

**6. Create Pull Request**:
- Go to GitHub repository
- Click "New Pull Request"
- Select `feature/my-feature` → `main`
- Describe changes
- Submit

### Code Style

**PEP 8** (Python style guide):
```python
# Good
def my_function(param1: str, param2: int) -> bool:
    """Do something useful."""
    if param1 and param2 > 0:
        return True
    return False

# Bad
def MyFunction(param1,param2):
    if param1 and param2>0:return True
    return False
```

**Type Hints**:
```python
from pathlib import Path
from typing import Optional

def build_project(project_path: Path, 
                  optimization: Optional[str] = None) -> BuildResult:
    """Build project with optional optimization."""
    pass
```

**Docstrings**:
```python
def compile_file(self, source: Path, output: Path) -> bool:
    """
    Compile a single source file.
    
    Args:
        source: Path to source file (.c or .cpp)
        output: Path to output object file (.o)
    
    Returns:
        True if compilation succeeded, False otherwise
    
    Raises:
        FileNotFoundError: If source file doesn't exist
    """
    pass
```

### Testing

**Manual Testing Checklist**:
- [ ] Application starts without errors
- [ ] Can create new project
- [ ] Can open existing project
- [ ] Can build project (console)
- [ ] Can run executable
- [ ] Graphics projects work (mingw32)
- [ ] OpenMP projects work (mingw64)
- [ ] Settings dialog opens
- [ ] Theme changes apply
- [ ] No console errors during operation

**Automated Tests** (future):
```python
# tests/test_builder.py
import pytest
from cpplab.builder import Builder

def test_build_hello_world():
    """Test building simple hello world."""
    builder = Builder()
    result = builder.build_file("tests/fixtures/hello.cpp")
    assert result.success
    assert result.executable.exists()
```

## Debugging

### VS Code Launch Configuration

**File**: `.vscode/launch.json`

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: CppLab",
      "type": "debugpy",
      "request": "launch",
      "module": "src.cpplab",
      "justMyCode": false,
      "console": "integratedTerminal"
    }
  ]
}
```

**Usage**:
1. Open VS Code
2. Press F5 (or Run → Start Debugging)
3. Set breakpoints in code
4. Step through execution

### Print Debugging

```python
# Add debug prints
def build_project(self):
    print(f"DEBUG: Building project {self.project_name}")
    print(f"DEBUG: Sources: {self.sources}")
    
    result = self._do_build()
    
    print(f"DEBUG: Result: {result}")
    return result
```

**View Output**: Check terminal where you ran `python -m src.cpplab`

### Qt Debugging

**Show widget boundaries**:
```python
# Temporarily add to __init__
self.setStyleSheet("* { border: 1px solid red; }")
```

**Print object tree**:
```python
def print_tree(obj, indent=0):
    """Print Qt object tree."""
    print("  " * indent + obj.objectName() or str(type(obj)))
    for child in obj.children():
        print_tree(child, indent + 1)

# Usage
print_tree(self)
```

## UI Development

### Editing UI Files

**Method 1: Qt Designer** (visual):
```powershell
# Install Qt Designer
pip install pyqt6-tools

# Run Designer
python -m PyQt6.QtDesigner

# Open MainWindow.ui
# Make changes
# Save
```

**Method 2: Hand-Edit XML**:
```powershell
code src/cpplab/ui/MainWindow.ui
```

**Reload UI**:
```python
# UI is loaded at runtime, just restart app
python -m src.cpplab
```

### Adding New Widgets

**In Qt Designer**:
1. Open `MainWindow.ui`
2. Drag widget from left panel
3. Set `objectName` property (e.g., `myButton`)
4. Save

**In Python**:
```python
# Access widget by objectName
self.myButton.clicked.connect(self.on_my_button_clicked)

def on_my_button_clicked(self):
    """Handle button click."""
    print("Button clicked!")
```

## Building Executable

### PyInstaller

**Install**:
```powershell
pip install pyinstaller
```

**Build**:
```powershell
pyinstaller --onefile --windowed ^
    --icon=resources/icon.ico ^
    --add-data "src/cpplab/ui;cpplab/ui" ^
    --add-data "compilers;compilers" ^
    --name CppLab ^
    src/cpplab/__main__.py
```

**Output**:
```
dist/
└── CppLab.exe    (~100-120 MB)
```

**Test**:
```powershell
.\dist\CppLab.exe
```

### Build Script

**File**: `build.ps1`

```powershell
# Build script for CppLab IDE

Write-Host "Building CppLab IDE..." -ForegroundColor Green

# Clean previous build
if (Test-Path dist) {
    Remove-Item -Recurse -Force dist
}
if (Test-Path build) {
    Remove-Item -Recurse -Force build
}

# Build with PyInstaller
pyinstaller --onefile --windowed `
    --icon=resources/icon.ico `
    --add-data "src/cpplab/ui;cpplab/ui" `
    --add-data "compilers;compilers" `
    --name CppLab `
    src/cpplab/__main__.py

Write-Host "Build complete!" -ForegroundColor Green
Write-Host "Executable: dist/CppLab.exe" -ForegroundColor Cyan
```

**Usage**:
```powershell
.\build.ps1
```

## Common Issues

### Issue 1: ModuleNotFoundError

**Error**:
```
ModuleNotFoundError: No module named 'PyQt6'
```

**Solution**:
```powershell
# Make sure venv is activated
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### Issue 2: UI File Not Found

**Error**:
```
FileNotFoundError: [Errno 2] No such file or directory: 'ui/MainWindow.ui'
```

**Solution**: Check that `src/cpplab/ui/MainWindow.ui` exists

```python
# In app.py, use absolute path
ui_path = Path(__file__).parent / "ui" / "MainWindow.ui"
uic.loadUi(ui_path, self)
```

### Issue 3: Toolchains Not Found

**Error**:
```
No toolchains found
```

**Solution**: Check `compilers/` directory structure

```
compilers/
├── mingw32/
│   └── bin/
│       ├── gcc.exe
│       └── g++.exe
└── mingw64/
    └── bin/
        ├── gcc.exe
        └── g++.exe
```

### Issue 4: Build Freezes UI

**Symptom**: UI freezes when building

**Solution**: Ensure async build system is used

```python
# Check that BuildWorker is used
worker = BuildWorker(...)
thread = QThread()
worker.moveToThread(thread)
thread.start()
```

## Contributing

### Pull Request Process

1. **Fork Repository**
2. **Clone Your Fork**:
   ```powershell
   git clone https://github.com/YOUR_USERNAME/CppLabEngine.git
   ```
3. **Create Branch**:
   ```powershell
   git checkout -b feature/my-feature
   ```
4. **Make Changes**
5. **Commit**:
   ```powershell
   git commit -m "Add feature: description"
   ```
6. **Push**:
   ```powershell
   git push origin feature/my-feature
   ```
7. **Create PR on GitHub**
8. **Wait for Review**
9. **Address Feedback**
10. **Merge** (by maintainer)

### Commit Message Format

**Format**:
```
<type>(<scope>): <subject>

<body>

<footer>
```

**Examples**:
```
feat(ui): Add dark theme support

Implemented dark theme with QSS stylesheets.
Users can now switch between classic and dark themes.

Closes #123
```

```
fix(build): Fix async build cancellation

BuildWorker now properly handles thread interruption.
Prevents crashes when user closes app during build.

Fixes #456
```

**Types**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `style`: Code style (formatting)
- `refactor`: Code refactoring
- `test`: Add tests
- `chore`: Maintenance

## Resources

**Python**:
- [Python Docs](https://docs.python.org/3/)
- [PEP 8 Style Guide](https://pep8.org/)

**PyQt6**:
- [PyQt6 Docs](https://www.riverbankcomputing.com/static/Docs/PyQt6/)
- [Qt6 Docs](https://doc.qt.io/qt-6/)

**Git**:
- [Git Docs](https://git-scm.com/doc)
- [GitHub Flow](https://guides.github.com/introduction/flow/)

**MinGW**:
- [MinGW-w64](https://www.mingw-w64.org/)
- [GCC Docs](https://gcc.gnu.org/onlinedocs/)

---

**Next**: [Building and Distribution](Building-And-Distribution.md)  
**Previous**: [Performance and Benchmarks](Performance-And-Benchmarks.md)