Skip to content

Development Setup

Jump to bottom
techy4shri edited this page Nov 25, 2025 · 1 revision

Development Setup

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

Prerequisites

Required Software

Python 3.13+:

# 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):

pip --version

Optional Tools

Git (for version control):

git --version

Download: https://git-scm.com/

VS Code (recommended IDE):

Qt Designer (for UI editing):

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

Why? Isolate dependencies from system Python

# 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):

deactivate

3. Install Dependencies

From requirements.txt:

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:

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:

ls compilers\

# Should show:
# mingw32/
# mingw64/

Test mingw64:

.\compilers\mingw64\bin\g++ --version

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

Test mingw32:

.\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

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:

git checkout -b feature/my-feature

2. Make Changes:

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

3. Test Changes:

# Run from source
python -m src.cpplab

# Test manually (build, run, etc.)

4. Commit Changes:

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

5. Push to GitHub:

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):

# 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:

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:

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):

# 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

{
  "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

# 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:

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

Print object tree:

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):

# Install Qt Designer
pip install pyqt6-tools

# Run Designer
python -m PyQt6.QtDesigner

# Open MainWindow.ui
# Make changes
# Save

Method 2: Hand-Edit XML:

code src/cpplab/ui/MainWindow.ui

Reload UI:

# 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:

# 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:

pip install pyinstaller

Build:

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:

.\dist\CppLab.exe

Build Script

File: build.ps1

# 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:

.\build.ps1

Common Issues

Issue 1: ModuleNotFoundError

Error:

ModuleNotFoundError: No module named 'PyQt6'

Solution:

# 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

# 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

# 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: 
    git clone https://github.com/YOUR_USERNAME/CppLabEngine.git
  3. Create Branch: 
    git checkout -b feature/my-feature
  4. Make Changes
  5. Commit: 
    git commit -m "Add feature: description"
  6. Push: 
    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:

PyQt6:

Git:

MinGW:

Next: Building and Distribution
Previous: Performance and Benchmarks

💡 Found this wiki useful?
⭐ Star the repo  ·  💖 Sponsor this project  ·  📦 Latest release  ·  🐞 Report an issue

Clone this wiki locally