CFDesktop 文档

Appearance

快速开始指南 ​

30 分钟内搭建 CFDesktop 开发环境

目录 ​

前置条件 ​

在开始之前，请确保已安装以下工具：

需求最低版本推荐版本检查命令
Git2.30+最新版git --version
CMake3.163.20+cmake --version
Qt66.8.36.8+检查 Qt 安装目录
编译器LLVM/Clang 或 GCC最新版clang --version 或 gcc --version
Docker（可选）20.10+最新版docker --version

平台特定要求 ​

Windows：

  • 需要使用 Git Bash 或 WSL2 来运行构建脚本
  • 需要安装 Qt6，并配置 MinGW 或 LLVM-MinGW 工具链
  • Windows 专用脚本需要 PowerShell 5.1+

Linux：

  • GCC 12+ 或 Clang 16+
  • Qt6 开发包
  • Ninja 构建系统（可选，但推荐安装）

五步快速开始 ​

第 1 步：克隆仓库 ​

bash
git clone https://github.com/Awesome-Embedded-Learning-Studio/CFDesktop.git
cd CFDesktop

第 2 步：安装 VSCode 扩展 ​

安装以下 VSCode 扩展以获得最佳开发体验：

扩展用途是否必需
ClangdC++ 语言服务器是
CMakeCMake 语法高亮推荐
CMake ToolsCMake 集成推荐
Qt for PythonQt 支持可选

快速安装（命令面板）：

  1. 按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS）
  2. 输入 "Extensions: Install Extensions"
  3. 搜索上方的每个扩展名称

第 3 步：Docker 首次构建（推荐） ​

最快的上手方式是使用 Docker，它提供了预配置的构建环境：

bash
# Fast build (reuses existing image if available)
bash scripts/build_helpers/docker_start.sh --fast-build --build-project-fast

此命令会执行以下操作：

  1. 构建（或复用）包含所有依赖的 Docker 镜像
  2. 使用 CMake 配置项目
  3. 构建所有模块（base、ui、examples）
  4. 将输出放置在 out/build_develop/ 目录中

Docker 选项：

选项说明
--fast-build跳过镜像清理，复用已有镜像
--build-project完整的干净构建
--build-project-fast快速增量构建
--run-project-test构建并运行测试
--arch arm64为 ARM64 架构构建
--verify运行 CI 风格的验证构建

第 4 步：运行示例程序 ​

构建成功后，运行示例程序：

Windows：

powershell
# Material Design Gallery
.\out\build_develop\examples\gui\material_gallery.exe

# Button Widget Example
.\out\build_develop\examples\ui\button.exe

# CPU Information Demo
.\out\build_develop\examples\base\cpu_info.exe

Linux：

bash
# Material Design Gallery
./out/build_develop/examples/gui/material_gallery

# Button Widget Example
./out/build_develop/examples/ui/button

# CPU Information Demo
./out/build_develop/examples/base/cpu_info

可用示例：

分类示例说明
base/cpu_info, memory_info系统信息演示
ui/button, label, textfield, checkbox, radiobutton, textarea, groupboxMaterial Design 控件
gui/material_gallery, theme完整 UI 演示

第 5 步：运行测试 ​

通过运行测试套件验证构建：

Windows：

powershell
.\scripts\build_helpers\windows_run_tests.ps1

Linux：

bash
bash scripts/build_helpers/linux_run_tests.sh

Docker：

bash
bash scripts/build_helpers/docker_start.sh --run-project-test

Windows 用户 ​

使用 Git Bash ​

CFDesktop 的构建脚本为 Unix 风格的 shell 设计。在 Windows 上，请使用 Git Bash：

  1. 安装 Git for Windows
  2. 从开始菜单打开 Git Bash
  3. 导航到项目目录：
    bash
    cd /d/ProjectHome/CFDesktop

使用 WSL2（替代方案） ​

为了获得更好的性能，可以使用 Windows Subsystem for Linux：

  1. 安装 WSL2：

    powershell
    wsl --install

  2. 从 WSL 中访问 Windows 文件：

    bash
    cd /mnt/d/ProjectHome/CFDesktop

路径格式转换 ​

在 Windows 上运行脚本时，请注意路径格式的差异：

类型格式示例
WindowsD:\Path\To\FileD:/ProjectHome/CFDesktop
Git Bash/d/Path/To/File/d/ProjectHome/CFDesktop
Docker 挂载/d/Path/To/File/d/ProjectHome/CFDesktop
PowerShellD:\Path\To\FileD:\ProjectHome\CFDesktop

构建脚本会自动处理 Docker 挂载的路径转换。

Windows 构建脚本 ​

对于原生 Windows 构建（不使用 Docker），请使用 PowerShell 脚本：

powershell
# Configure and build (fast)
.\scripts\build_helpers\windows_fast_develop_build.ps1

# Configure and build (full clean)
.\scripts\build_helpers\windows_develop_build.ps1

# Configure only
.\scripts\build_helpers\windows_configure.ps1

# Run tests
.\scripts\build_helpers\windows_run_tests.ps1

验证 ​

检查 Docker 安装 ​

bash
# Verify Docker is installed
docker --version

# Verify Docker daemon is running
docker info

预期输出：

text
Docker version 20.10.x
...
Server Version: 20.10.x

检查构建是否成功 ​

构建成功后会创建以下目录结构：

text
out/build_develop/
├── bin/
│   ├── cfbase.dll          # Base library (Windows)
│   ├── cfui.dll            # UI library (Windows)
│   └── ...
├── lib/
│   ├── libcfbase.a         # Static libraries (Linux)
│   └── ...
├── examples/
│   ├── base/               # Base examples
│   ├── ui/                 # UI widget examples
│   └── gui/                # GUI examples
├── runtimes/               # Qt runtime DLLs (Windows)
└── test/                   # Test executables

检查构建日志 ​

使用 Docker 时，构建日志保存在 scripts/docker/logger/ 中：

bash
# List recent build logs
ls -lt scripts/docker/logger/

# View the latest log
cat scripts/docker/logger/ci_build_*.log | tail -50

后续步骤 ​

完成快速开始后：

  1. 阅读构建系统文档：03_build_system.md
  2. 探索示例程序：浏览 example/ 目录中的示例代码
  3. 了解项目结构：查看项目骨架设计
  4. 配置开发环境：参考 VSCode 配置

常见问题排查 ​

Docker 构建失败 ​

问题解决方案
Docker 守护进程未运行启动 Docker Desktop
权限不足在 Linux 上使用 sudo，或在 Windows 上以管理员身份运行终端
端口冲突确保没有其他容器占用所需端口
内存不足在设置中增加 Docker 内存限制

构建错误 ​

问题解决方案
未找到 Qt设置 Qt6_DIR 环境变量，或使用 Docker 构建
未找到编译器安装 LLVM/Clang 或 GCC，或使用 Docker 构建
CMake 版本过低将 CMake 升级到 3.16+
缺少依赖使用 Docker 构建，其中包含所有依赖

Windows 特定问题 ​

问题解决方案
路径过长在 Windows 中启用长路径支持，或将项目移到更靠近驱动器根目录的位置
PowerShell 执行策略限制运行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Git Bash 路径问题使用 /d/ 格式表示 D: 盘

获取帮助 ​

如果遇到本文未涵盖的问题：

  1. 查看设计文档获取详细信息
  2. 参考构建系统文档
  3. 在 GitHub 上提交 issue

快速参考 ​

常用命令 ​

bash
# Clone and setup
git clone https://github.com/Awesome-Embedded-Learning-Studio/CFDesktop.git
cd CFDesktop

# Docker build (fastest)
bash scripts/build_helpers/docker_start.sh --fast-build --build-project-fast

# Run tests
bash scripts/build_helpers/docker_start.sh --run-project-test

# Interactive shell in Docker
bash scripts/build_helpers/docker_start.sh

# Build specific architecture
bash scripts/build_helpers/docker_start.sh --arch arm64 --verify

配置文件 ​

文件用途
build_develop_config.ini开发构建配置
build_deploy_config.ini部署构建配置
build_ci_config.iniCI 构建配置

输出目录 ​

构建类型输出目录
开发out/build_develop/
部署out/build_deploy/
CIout/build_ci/

Last Updated: 2026-03-07

Built with VitePress

Copyright © 2026 CharlieChen