Skip to content

Awesome-Embedded-Learning-Studio/CFDesktop

BranchesTags

Repository files navigation

CFDesktop

为嵌入式设备打造的现代化 Material Design 3 桌面框架

[License: MIT] [Version: 0.19.0] [C++23] [Qt 6.8] [CMake] [Documentation]

项目简介 • 项目进度 • 架构概览 • 快速开始

项目简介

CFDesktop 是一个基于 Qt6 的嵌入式桌面框架项目，旨在解决以下问题：

解决的问题

  • 嵌入式设备 UI 现代化 - 提供符合 Material Design 3 规范的现代 UI
  • 性能自适应 - 根据设备硬件能力动态调整 UI 复杂度，从低端 ARM 到高性能 RK3588 都能流畅运行
  • 开发效率低 - 提供完整的 SDK 和模拟器，简化嵌入式 GUI 应用开发
  • 跨平台移植难 - 模块化设计，易于移植到不同架构 (x86_64/ARM64/ARMhf)

目标用户

  • 想尝试部署所有端统一的桌面模拟器的嵌入式Linux爱好者
  • Qt 应用开发爱好者（嘿！想想一个All Same的桌面，可以运行在imx6ull，rk系列甚至是上位机的桌面！）
  • 嵌入式 Linux 系统集成商（幻想开始.png）

AI Agent 支持

本项目内置 AI agent 协作支持（Claude Code 与 Codex CLI），项目约定集中在 AGENT.md（单一来源，CLAUDE.md / AGENTS.md 为各工具入口）。使用 AI 时据此快速理解架构与规范；不使用 AI 可安全忽略 AGENT.md / CLAUDE.md / AGENTS.md 与 .claude/ 目录，它们不影响构建。

项目进度

项目进度以 document/status/current.md 为唯一事实来源。以下为对外概览，可能滞后，精确状态请查阅该文件。

当前焦点：跑通「看到桌面 → 点图标 → 开应用」最小闭环。

  • ✅ base 硬件探针层（含 HWTier）完成
  • 🚧 ui / desktop 核心就绪，最小闭环控件与后端开发中
  • ⬜ 输入抽象、模拟器、Wayland / 嵌入式后端待开始

下一步路线与各 Phase 细节见 document/status/current.md，待办清单见 document/todo/。

架构概览

分层设计

┌─────────────────────────────────────────────────────────────────┐
│                    Material Widget Layer                         │
│  (P0: 7控件 ✅ | P1: 12控件 ✅ | P2: 27控件 ⬜ | P3: 25控件 ⬜)    │
├─────────────────────────────────────────────────────────────────┤
│                    Material Behavior Layer (100%)                │
│  StateMachine | RippleHelper | ElevationController | FocusRing   │
├─────────────────────────────────────────────────────────────────┤
│                     Animation Engine Layer (90%)                 │
│  AnimationFactory | Fade/Slide/Scale ✅                         │
├─────────────────────────────────────────────────────────────────┤
│                      Theme Engine Layer (100%)                   │
│  ThemeManager | ColorScheme | Typography | Motion | Radius      │
├─────────────────────────────────────────────────────────────────┤
│                    Math & Utility Layer (100%)                   │
│  MathHelper | Color | Easing | Geometry | DevicePixel           │
├─────────────────────────────────────────────────────────────────┤
│                      Desktop Base Layer (85%)                    │
│  ConfigStore | Logger | ASCII Art | File Operations | System    │
└─────────────────────────────────────────────────────────────────┘

模块说明

模块 路径 功能
配置中心 desktop/base/config_manager/ 四层存储 (Temp/App/User/System)、变更监听、JSON 持久化
日志系统 desktop/base/logger/ 多等级日志、异步处理、多 Sink 支持
文件操作 desktop/base/file_operations/ 跨平台文件操作、权限管理、监控
ASCII 艺术 desktop/base/ascii_art/ 启动 Logo 渲染、ASCII 图形
系统检测 base/system/ CPU/Memory 信息检测、跨平台支持
设备抽象 base/device/ 控制台设备抽象层、策略链
基础工具 base/include/base/ Hash、Optional、ScopeGuard、Singleton 等
UI 核心 ui/core/ Material Design 主题引擎、Token 系统
UI 组件 ui/components/ 动画工厂、动画组、策略模式
UI 控件 ui/widget/material/ Material Design 控件实现

Display Backend

CFDesktop 通过 IDisplayServerBackend 接口抽象了三种显示模式，使 Shell、PanelManager 和 WindowManager 可以在不同平台上一致工作：

  • Client 模式: 作为现有桌面环境内的应用运行（Windows、Linux Gnome/KDE）
  • Compositor 模式: CFDesktop 自身作为显示服务器/合成器管理外部应用窗口（X11/Wayland）
  • DirectRender 模式: 直接渲染到 framebuffer，无需窗口系统（嵌入式 EGLFS/linuxfb）
后端 状态 说明
Windows 后端 100% Win32 DWM 集成、SetWinEventHook 窗口管理
WSL X11 后端 100% XCB + XWayland、QSocketNotifier 驱动
Wayland 合成器 0% 待实现
EGLFS / LinuxFB 0% 嵌入式直驱，待实现

后端通过 DisplayServerBackendFactory 工厂在启动时自动选择平台实现。

技术栈

  • 语言: C++23
  • 框架: Qt 6.8.3
  • 构建: CMake 3.16+, Ninja
  • 测试: Google Test
  • 文档: VitePress + Doxygen

快速开始

前置要求

  • C++23 编译器 (LLVM/Clang 或 GCC)
  • CMake 3.16+
  • Qt 6.8+

构建项目

# 克隆仓库
git clone https://github.com/Awesome-Embedded-Learning-Studio/CFDesktop
cd CFDesktop

# Windows 快速构建
.\scripts\build_helpers\windows_fast_develop_build.ps1

# Linux 快速构建
./scripts/build_helpers/linux_fast_develop_build.sh

运行示例

# 运行 Material Gallery (查看所有 UI 组件)
.\out\build_deploy\bin\material_gallery.exe

# 运行主题定制示例
.\out\build_deploy\bin\material_theme_customizer.exe

开发环境配置

项目使用 VSCode + Clangd 作为推荐开发环境，首次构建后会自动生成配置文件。

详细配置说明: document/development/README.md

完整文档

📚 项目文档站: https://awesome-embedded-learning-studio.github.io/CFDesktop/

本地预览文档:

pnpm install
pnpm dev
pnpm build

开发文档

文档 说明 链接
开发环境设置 前置要求、快速开始、构建系统 development/
当前状态 开发重启事实源 status/current
UI 框架文档 Material Design 实现架构 HandBook/ui/
AI 辅助开发 通用 AI 协作指南 development/ai-assistant-guide

设计文档

文档 说明 链接
工程骨架设计 项目基础设施与环境配置 design_stage/00_phase0_project_skeleton.md
Base 库设计 基础库设计与实现 design_stage/02_phase2_base_library.md
UI 框架设计 Material Design 分层架构 HandBook/ui/architecture/

TODO 跟踪

贡献

欢迎贡献代码、报告问题或提出建议！

请查看 document/todo/ 了解当前开发任务和优先级。

许可证

本项目采用 MIT 开源许可证。

很早就像做一个酷酷的统一桌面，现在，终于可以尝试开始了！

About

This is a Repo that Desktop can be deployed on Any Embedded Device enable to run Qt

awesome-embedded-learning-studio.github.io/CFDesktop/

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

6 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages