Development Setup

Prerequisites

Required Software

# Check version
python --version
# Should output: Python 3.13.0 or higher

pip --version

Optional Tools

git --version

pip install pyqt6-tools

Initial Setup

1. Clone Repository

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

2. Create Virtual Environment

# 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

3. Install Dependencies

pip install -r requirements.txt

PyQt6==6.6.1
PyQt6-Qt6==6.6.1
PyQt6-sip==13.6.0

pip list
# Should show:
# PyQt6 6.6.1
# PyQt6-Qt6 6.6.1
# PyQt6-sip 13.6.0

4. Verify MinGW Toolchains

ls compilers\
# Should show:
# mingw32/
# mingw64/

.\compilers\mingw64\bin\g++ --version
# Should output:
# g++ (MinGW-W64 ...) 8.1.0

.\compilers\mingw32\bin\g++ --version
# Should output:
# g++ (MinGW.org ...) 8.1.0

5. Run from Source

# Activate venv (if not already)
.\venv\Scripts\activate
# Run application
python -m src.cpplab
# Alternative
python src/cpplab/__main__.py

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

git checkout -b feature/my-feature

# Edit files in src/cpplab/
code src/cpplab/app.py

# Run from source
python -m src.cpplab
# Test manually (build, run, etc.)

git add .
git commit -m "Add feature: my feature"

git push origin feature/my-feature

Code Style

# 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

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

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

# 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

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

Print Debugging

# 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

Qt Debugging

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

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

# Install Qt Designer
pip install pyqt6-tools
# Run Designer
python -m PyQt6.QtDesigner
# Open MainWindow.ui
# Make changes
# Save

code src/cpplab/ui/MainWindow.ui

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

Adding New Widgets

# 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

pip install 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

dist/
└── CppLab.exe (~100-120 MB)

.\dist\CppLab.exe

Build Script

# 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

.\build.ps1

Common Issues

Issue 1: ModuleNotFoundError

ModuleNotFoundError: No module named 'PyQt6'

# Make sure venv is activated
.\venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt

Issue 2: UI File Not Found

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

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

Issue 3: Toolchains Not Found

No toolchains found

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

Issue 4: Build Freezes UI

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

Contributing

Pull Request Process

Commit Message Format

<type>(<scope>): <subject>
<body>
<footer>

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

Resources