Project Optimization Summary

February 25, 2026 · View on GitHub

This document records the optimization improvements made to cge-tools based on lessons from the darkwarrior project.

Optimizations

1. CMakeLists.txt Optimizations

1.1 CCache Support

# Auto-detect and enable ccache to speed up compilation
find_program(CCACHE_FOUND ccache)
if(CCACHE_FOUND)
    set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)
    set_property(GLOBAL PROPERTY RULE_LAUNCH_LINK ccache)
    message(STATUS "Using ccache for compilation")
endif()

Benefit: Can significantly reduce compile time on repeated builds (5–10x speedup)

1.2 Qt Auto-detection

# Auto-detect Qt installation paths using multiple methods
if(NOT DEFINED Qt_DIR OR NOT EXISTS ${Qt_DIR})
    if(DEFINED ENV{QTDIR})
        set(Qt_DIR $ENV{QTDIR})
    elseif(DEFINED ENV{QT_DIR})
        set(Qt_DIR $ENV{QT_DIR})
    else()
        # Derive Qt path from qmake
        find_program(MY_QMAKE_NAME qmake)
        if(MY_QMAKE_NAME)
            get_filename_component(MY_QMAKE_DIR ${MY_QMAKE_NAME} DIRECTORY)
            get_filename_component(Qt_DIR ${MY_QMAKE_DIR} DIRECTORY)
        endif()
    endif()
endif()

Benefits:

  • No need to set the Qt path manually
  • Supports multiple Qt configuration methods
  • Automatically detects Qt version

1.3 Cross-platform Compiler Configuration

# macOS/Linux: suppress deprecation warnings
if(NOT CMAKE_HOST_SYSTEM_NAME MATCHES "Windows")
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-deprecated-declarations")
endif()

# Windows MSVC: optimized compile options
if(MSVC)
    add_compile_options(
        /utf-8          # UTF-8 source encoding
        /MP             # Multi-processor compilation
        /W1             # Warning level
        /D_USE_MATH_DEFINES
        /DWIN32_LEAN_AND_MEAN
    )
endif()

Benefits: Better cross-platform support and improved compile experience

2. VSCode Configuration (.vscode/)

2.1 settings.json

  • CMake tools integration
  • Auto-configure C/C++ IntelliSense
  • Many file type associations
  • Disable error squiggles (provided by CMake tools)

Usage:

  • Configuration loads automatically when the project is opened
  • Cmd/Ctrl + Shift + P → "CMake: Configure" to configure the project

2.2 c_cpp_properties.json

  • Complete include path configuration
  • Multi-platform configurations (macOS, Linux, Windows)
  • Framework path settings
  • C++11 standard configuration

Benefits: More accurate IntelliSense auto-completion and code hints

2.3 tasks.json

Provides several convenient build tasks:

  • Configure CMake (Debug/Release): Configure the CMake project
  • Build cge (Debug/Release): Build the library
  • Clean Build: Clean the build directory
  • Rebuild (Debug/Release): Rebuild

Usage:

  • Cmd/Ctrl + Shift + B: Run the default build task
  • Cmd/Ctrl + Shift + P → "Tasks: Run Task" → select a task

2.4 launch.json

Debug configurations:

  • lldb (macOS)
  • gdb (Linux)
  • msvc (Windows)

Usage:

  • F5: Start debugging
  • Set breakpoints in example programs and debug

3. Code Formatting (.clang-format)

Custom configuration based on LLVM style:

  • 4-space indentation
  • Newline after functions/classes
  • 120-character column limit
  • C++11 standard

Usage:

# Format all code
./format-all.sh

# Or use VSCode
Right-click → "Format Document" or Shift+Alt+F

4. Build Script (tasks.sh)

Full-featured build script:

# View help
./tasks.sh --help

# Clean build
./tasks.sh --clean

# Configure project
./tasks.sh --config

# Build project
./tasks.sh --build

# Full rebuild (recommended)
./tasks.sh --rebuild

# Release build
./tasks.sh --release --rebuild

# Build single file for syntax check
./tasks.sh --build-single-file filterGenerator/widgets/canvasWidget.cpp

# Format code
./tasks.sh --format

Features:

  • Colored output
  • Automatically detects CPU core count for parallel builds
  • Shows build artifact size
  • Error handling

5. .gitignore Improvements

More complete ignore rules:

  • Various IDE configuration files
  • Multiple build artifacts
  • OS-specific files
  • Documentation build outputs
  • Example program outputs

Quick Start

Command Line

# 1. Rebuild project
./tasks.sh --release --rebuild

# 2. View build artifacts
ls -lh build/libcge.a

# 3. Install library (optional)
./tasks.sh --install

VSCode

  1. Open the project folder
  2. CMake configuration prompt appears automatically (or manually: Cmd+Shift+P → "CMake: Configure")
  3. Press Cmd+Shift+B to build
  4. Press F5 to debug example programs

VSCode Tasks

  1. Cmd+Shift+P → "Tasks: Run Task"
  2. Select the desired task:
    • Configure CMake (Debug)
    • Build cge (Release)
    • Rebuild (Debug)
    • etc.

Performance Comparison

OperationBeforeAfterImprovement
First compile~25s~22s12%
Repeated compile (ccache)~25s~3s8x
Qt path configManualAuto—
Code formattingManualOne-click—

Best Practices

Development Workflow

  1. Edit code

    # Edit in VSCode
# Auto-format on save (if enabled)

  2. Format code (optional)

    ./format-all.sh

  3. Build and test

    # Debug build (for development)
./tasks.sh --debug --rebuild

# Release build (for release)
./tasks.sh --release --rebuild

Git Workflow

# 1. Create branch
git checkout -b feature/my-feature

# 2. Edit code and format
./format-all.sh

# 3. Commit
git add .
git commit -m "Add new feature"

# 4. Build test
./tasks.sh --release --rebuild

# 5. Push
git push origin feature/my-feature

Comparison with darkwarrior Project

Featuredarkwarriorcge-toolsNotes
CCache✅✅Ported
Qt auto-detection✅✅Ported
OpenMP✅❌Not needed by cge
ANGLE✅❌cge uses system OpenGL
OpenCV✅❌cge has no CV dependency
Architecture detection (arm64/x86_64)✅⚠️Not fully implemented
POST_BUILD script✅❌Not currently needed
.vscode config✅✅Ported
tasks.sh✅✅Simplified version
.clang-format✅✅Ported

Items to Improve

  1. Architecture detection: Add more complete arm64/x86_64 detection and configuration
  2. OpenMP support: Add OpenMP if parallel processing is needed
  3. Unit tests: Add CTest integration
  4. Documentation generation: Doxygen automation
  5. CI/CD: GitHub Actions automated builds
  6. Package management: Support vcpkg/conan

References

FAQ

Q: ccache not installed?

# macOS
brew install ccache

# Linux
sudo apt-get install ccache

# Windows
choco install ccache

Q: Qt path detection failed?

# Set environment variable
export QTDIR=/path/to/Qt/6.7.1/macos

# Or use CMake parameter
cmake -DCMAKE_PREFIX_PATH=/path/to/Qt/6.7.1/macos ..

Q: VSCode IntelliSense not working?

  1. Install "C/C++" and "CMake Tools" extensions
  2. Run "CMake: Configure"
  3. Reload window

Q: tasks.sh has no execute permission?

chmod +x tasks.sh format-all.sh

Documentation generated: 2026-02-16 Version: 1.0.0