# VoiletCStudio 需求规格说明书 **版本号：** v1.0 **项目名称：** 紫罗兰 C 工程配置器（VoiletCStudio） **开发日期：** 2026-04-09 **作者：** 虾哥 --- ## 📋 目录 1. [项目概述](#1-项目概述) 2. [功能需求](#2-功能需求) 3. [界面设计](#3-界面设计) 4. [技术规格](#4-技术规格) 5. [使用说明](#5-使用说明) 6. [文件结构](#6-文件结构) 7. [配置文件格式](#7-配置文件格式) 8. [编译流程](#8-编译流程) --- ## 1. 项目概述 ### 1.1 项目背景 VoiletCStudio 是一款跨平台的 C 工程配置工具，旨在简化 C 语言项目的构建流程。通过图形化界面管理工程配置，自动生成 CMakeLists.txt 文件，支持一键编译 Debug 和 Release 版本。 ### 1.2 目标用户 - C 语言开发者 - 嵌入式系统开发人员 - 需要跨平台编译的项目团队 - 从 IDE 迁移到 CMake 的开发者 ### 1.3 核心价值 - **简化配置**：图形化界面替代手动编写 CMakeLists.txt - **跨平台支持**：Windows (MinGW) / Linux (GCC) / macOS (Clang) - **提高效率**：一键生成和编译，减少重复劳动 - **易于上手**：类似 MDK 的虚拟目录管理，降低学习成本 --- ## 2. 功能需求 ### 2.1 工程文件管理 | 功能 ID | 功能名称 | 功能描述 | 优先级 | |--------|---------|---------|--------| | F-001 | 新建工程 | 创建新的 C 工程配置 | 高 | | F-002 | 打开工程 | 加载已保存的 JSON 配置文件 | 高 | | F-003 | 保存工程 | 保存当前配置到 JSON 文件 | 高 | | F-004 | 另存为 | 将工程保存到指定位置 | 中 | | F-005 | 拖拽打开 | 拖拽 JSON 文件到窗口打开工程 | 中 | ### 2.2 编译工具链配置 | 功能 ID | 功能名称 | 功能描述 | 优先级 | |--------|---------|---------|--------| | F-010 | 编译器配置 | 设置 C 编译器路径（gcc/clang 等） | 高 | | F-011 | 汇编器配置 | 设置汇编器路径 | 中 | | F-012 | 链接器配置 | 设置链接器路径 | 中 | ### 2.3 文件管理 | 功能 ID | 功能名称 | 功能描述 | 优先级 | |--------|---------|---------|--------| | F-020 | 虚拟目录 | 创建类似 MDK 的虚拟文件夹 | 高 | | F-021 | 源文件管理 | 添加/移除 .c 源文件 | 高 | | F-022 | 包含目录 | 添加/移除 .h 头文件目录 | 高 | | F-023 | 库文件管理 | 添加/移除 .a/.so/.lib 库文件 | 高 | ### 2.4 编译配置 | 功能 ID | 功能名称 | 功能描述 | 优先级 | |--------|---------|---------|--------| | F-030 | 编译宏 | 添加/移除预编译宏定义 | 高 | | F-031 | 编译选项 | 添加/移除自定义编译参数 | 中 | ### 2.5 CMake 生成 | 功能 ID | 功能名称 | 功能描述 | 优先级 | |--------|---------|---------|--------| | F-040 | 生成 CMake | 自动生成 CMakeLists.txt 文件 | 高 | | F-041 | 命令提示 | 显示编译命令使用说明 | 高 | ### 2.6 编译功能 | 功能 ID | 功能名称 | 功能描述 | 优先级 | |--------|---------|---------|--------| | F-050 | 编译 Debug | 编译 Debug 版本（带调试信息） | 高 | | F-051 | 编译 Release | 编译 Release 版本（优化发布） | 高 | | F-052 | 实时输出 | 显示编译过程实时日志 | 高 | | F-053 | 自动清理 | 编译前自动清空 build 目录 | 高 | --- ## 3. 界面设计 ### 3.1 主界面布局 ``` ┌─────────────────────────────────────────────────────────────┐ │ VoiletCStudio - C 工程配置器 │ ├─────────────────────────────────────────────────────────────┤ │ ⚡ 快捷操作 │ │ [📂 打开] [📄 新建] [💾 保存] [🔨 生成 CMake] [🐛 编译 Debug] [🚀 编译 Release] │ ├─────────────────────────────────────────────────────────────┤ │ 📁 工程基本信息 │ │ 工程名：[____________] │ ├─────────────────────────────────────────────────────────────┤ │ 🔧 编译工具链 │ │ 编译器：[____] 汇编器：[____] 链接器：[____] │ ├─────────────────────────────────────────────────────────────┤ │ 📁 源文件 │ 📦 库文件 │ │ ├─ 📁 App │ ├─ libmylib.a │ │ │ ├─ main.c │ 🏷️ 编译宏 │ │ │ └─ utils.c │ ├─ DEBUG │ │ 📚 包含目录 │ ⚙️ 编译选项 │ │ ├─ ./include │ ├─ -Wall │ ├─────────────────────────────────────────────────────────────┤ │ 就绪 [状态栏] │ └─────────────────────────────────────────────────────────────┘ ``` ### 3.2 按钮说明 | 按钮 | 颜色 | 功能 | 快捷键 | |------|------|------|--------| | 📂 打开工程 | 🔵 蓝色 | 打开已有工程 | Ctrl+O | | 📄 新建工程 | 🟢 绿色 | 创建新工程 | Ctrl+N | | 💾 保存工程 | 🟠 橙色 | 保存配置 | Ctrl+S | | 🔨 生成 CMake | 🟣 紫色 | 生成 CMakeLists.txt | Ctrl+G | | 🐛 编译 Debug | 🔵 青色 | 编译 Debug 版本 | - | | 🚀 编译 Release | 🌸 粉色 | 编译 Release 版本 | - | --- ## 4. 技术规格 ### 4.1 开发环境 | 项目 | 规格 | |------|------| | 开发语言 | C++ 11 | | GUI 框架 | Qt 5 | | 构建系统 | qmake | | 目标平台 | Windows / Linux / macOS | ### 4.2 系统要求 | 项目 | 最低要求 | 推荐配置 | |------|---------|---------| | 操作系统 | Windows 7 / Ubuntu 18.04 / macOS 10.14 | Windows 10 / Ubuntu 20.04 / macOS 11+ | | 内存 | 512 MB | 2 GB | | 磁盘空间 | 100 MB | 500 MB | | 编译器 | GCC 5.0+ / MinGW / Clang | GCC 9.0+ / MinGW-w64 / Clang 10+ | ### 4.3 依赖库 | 库名称 | 版本 | 用途 | |--------|------|------| | Qt Core | 5.12+ | 核心功能 | | Qt GUI | 5.12+ | 图形界面 | | Qt Widgets | 5.12+ | 窗口组件 | | CMake | 3.10+ | 构建系统 | | GCC/MinGW | 5.0+ | C 编译器 | --- ## 5. 使用说明 ### 5.1 快速开始 #### 步骤 1：新建工程 1. 点击【📄 新建工程】按钮 2. 输入工程名称 3. 点击【💾 保存工程】，选择保存位置 #### 步骤 2：配置工具链 1. 点击编译器旁的【浏览】按钮 2. 选择编译器路径（如 `/usr/bin/gcc`） 3. 同样配置汇编器和链接器（通常与编译器相同） #### 步骤 3：添加源文件 1. 点击【➕ 目录】创建虚拟文件夹（如 "App"） 2. 选中目录，点击【➕ 文件】添加 .c 文件 3. 重复添加所有源文件 #### 步骤 4：配置包含目录 1. 切换到右侧"包含目录"面板 2. 点击【➕ 添加】选择头文件目录 3. 添加所有需要的包含路径 #### 步骤 5：添加库文件（可选） 1. 切换到"库文件"面板 2. 点击【➕ 添加】选择 .a/.so/.lib 文件 3. 添加所有依赖库 #### 步骤 6：配置编译选项 1. 切换到"编译宏"面板 2. 点击【➕ 添加】输入宏定义（如 `DEBUG`） 3. 切换到"编译选项"面板 4. 添加自定义编译参数（如 `-Wall`） #### 步骤 7：生成 CMake 1. 点击【🔨 生成 CMake】按钮 2. 查看弹出的编译命令提示 3. CMakeLists.txt 已生成到工程目录 #### 步骤 8：编译工程 **方式一：使用内置编译** 1. 点击【🐛 编译 Debug】或【🚀 编译 Release】 2. 查看编译输出窗口 3. 编译完成后查看结果 **方式二：手动编译** ```bash cd build make debug # 编译 Debug 版本 make release # 编译 Release 版本 ``` --- ## 6. 文件结构 ### 6.1 工程目录结构 ``` MyProject/ ├── config.json # 工程配置文件 ├── CMakeLists.txt # CMake 配置文件（自动生成） ├── build/ # 编译输出目录（自动生成） │ ├── Makefile # Makefile（自动生成） │ ├── debug/ # Debug 编译产物 │ │ └── MyProject # Debug 可执行文件 │ └── release/ # Release 编译产物 │ └── MyProject # Release 可执行文件 ├── src/ # 源文件目录（用户创建） │ ├── main.c │ └── utils.c └── include/ # 头文件目录（用户创建） └── utils.h ``` ### 6.2 源代码结构 ``` VoiletCStudio/ ├── src/ │ ├── main.cpp # 程序入口 │ ├── mainwindow.cpp/h # 主窗口实现 │ ├── projectconfig.cpp/h # 配置管理 │ └── cmakegenerator.cpp/h # CMake 生成 ├── VoiletCStudio.pro # Qt 项目文件 ├── README.md # 使用说明 └── 需求规格说明书.md # 本文档 ``` --- ## 7. 配置文件格式 ### 7.1 JSON 配置示例 ```json { "projectName": "MyProject", "projectPath": "/home/anonymous/Desktop/MyProject", "compilerPath": "/usr/bin/gcc", "assemblerPath": "/usr/bin/gcc", "linkerPath": "/usr/bin/gcc", "outputDir": "./build", "virtualDirs": { "App": { "name": "App", "files": [ "/home/anonymous/Desktop/MyProject/src/main.c", "/home/anonymous/Desktop/MyProject/src/utils.c" ] }, "Drivers": { "name": "Drivers", "files": [ "/home/anonymous/Desktop/MyProject/src/drivers/driver.c" ] } }, "includeDirs": [ "/home/anonymous/Desktop/MyProject/include" ], "libraries": [ "/usr/lib/libmylib.a" ], "defines": [ "DEBUG", "VERSION=1.0" ], "compilerOptions": [ "-Wall", "-Wextra" ] } ``` ### 7.2 字段说明 | 字段名 | 类型 | 说明 | 必填 | |--------|------|------|------| | projectName | string | 工程名称 | 是 | | projectPath | string | 工程路径 | 是 | | compilerPath | string | 编译器路径 | 是 | | assemblerPath | string | 汇编器路径 | 否 | | linkerPath | string | 链接器路径 | 否 | | outputDir | string | 输出目录 | 否 | | virtualDirs | object | 虚拟目录配置 | 是 | | includeDirs | array | 包含目录列表 | 否 | | libraries | array | 库文件列表 | 否 | | defines | array | 编译宏列表 | 否 | | compilerOptions | array | 编译选项列表 | 否 | --- ## 8. 编译流程 ### 8.1 CMake 生成流程 ``` 用户点击【生成 CMake】 ↓ 读取工程配置（JSON） ↓ 生成 CMakeLists.txt ↓ 显示编译命令提示 ↓ 完成 ``` ### 8.2 编译执行流程 ``` 用户点击【编译 Debug/Release】 ↓ 保存工程配置 ↓ 删除旧的 build 目录 ↓ 创建新的 build 目录 ↓ 生成 CMakeLists.txt ↓ 执行 cmake -DCMAKE_BUILD_TYPE=Debug/Release .. ↓ 执行 make debug/release ↓ 实时显示编译输出 ↓ 显示编译结果 ↓ 完成 ``` ### 8.3 CMakeLists.txt 结构 ```cmake # ======================================== # CMakeLists.txt - VoiletCStudio 自动生成 # 工程名称：MyProject # 生成时间：2026-04-09 10:00:00 # 跨平台支持：Windows (MinGW) / Linux (GCC) / macOS (Clang) # ======================================== cmake_minimum_required(VERSION 3.10) # 项目名称 project(MyProject C) # C 标准 set(CMAKE_C_STANDARD 11) set(CMAKE_C_STANDARD_REQUIRED ON) # 输出目录配置 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/./build) set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/./build) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/./build) # 编译器配置 set(CMAKE_C_COMPILER "/usr/bin/gcc") # ======================================== # 源文件配置（虚拟目录结构） # ======================================== # 分组：App set(SRCS_App /home/anonymous/Desktop/MyProject/src/main.c /home/anonymous/Desktop/MyProject/src/utils.c ) # 分组：Drivers set(SRCS_Drivers /home/anonymous/Desktop/MyProject/src/drivers/driver.c ) # 合并所有源文件 set(SOURCES /home/anonymous/Desktop/MyProject/src/main.c /home/anonymous/Desktop/MyProject/src/utils.c /home/anonymous/Desktop/MyProject/src/drivers/driver.c ) # 创建可执行文件 add_executable(MyProject ${SOURCES}) # 包含目录 target_include_directories(MyProject PRIVATE /home/anonymous/Desktop/MyProject/include ) # 链接库 target_link_libraries(MyProject PRIVATE /usr/lib/libmylib.a ) # 预编译宏定义 target_compile_definitions(MyProject PRIVATE DEBUG VERSION=1.0 ) # 自定义编译选项 target_compile_options(MyProject PRIVATE -Wall -Wextra ) # ======================================== # 构建类型配置 # ======================================== # 默认构建类型：Debug if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Debug CACHE STRING "Build type" FORCE) endif() # Debug 模式配置（自动添加 DEBUG 宏） set(CMAKE_C_FLAGS_DEBUG "-g -O0 -DDEBUG" CACHE STRING "Debug flags" FORCE) # Release 模式配置 set(CMAKE_C_FLAGS_RELEASE "-O2 -DNDEBUG" CACHE STRING "Release flags" FORCE) # ======================================== # 自定义 Make 目标：make debug / make release # ======================================== # make debug - 编译 Debug 版本（自动添加 DEBUG 宏） add_custom_target(debug COMMAND ${CMAKE_COMMAND} -DCMAKE_BUILD_TYPE=Debug ${CMAKE_SOURCE_DIR} COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --config Debug COMMENT "Building Debug version" VERBATIM ) # make release - 编译 Release 版本 add_custom_target(release COMMAND ${CMAKE_COMMAND} -DCMAKE_BUILD_TYPE=Release ${CMAKE_SOURCE_DIR} COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --config Release COMMENT "Building Release version" VERBATIM ) # 使用说明： # cmake -B build # 配置（默认 Debug） # cmake --build build # 编译（使用当前 CMAKE_BUILD_TYPE） # make debug # 编译 Debug 版本（自动添加 DEBUG 宏） # make release # 编译 Release 版本 ``` --- ## 9. 常见问题 ### 9.1 编译失败 **问题：** 点击编译后提示找不到编译器 **解决：** 1. 检查编译器路径是否正确 2. 确认编译器已安装（`gcc --version`） 3. Windows 用户确认 MinGW 已正确安装 ### 9.2 CMake 生成失败 **问题：** 点击生成 CMake 无反应 **解决：** 1. 检查工程是否已保存 2. 确认保存路径有写入权限 3. 查看状态栏错误提示 ### 9.3 拖拽无反应 **问题：** 拖拽 JSON 文件到窗口没反应 **解决：** 1. 确认文件扩展名为 `.json` 2. 确认文件是有效的工程配置 3. 尝试使用"打开工程"按钮 --- ## 10. 版本历史 | 版本 | 日期 | 更新内容 | |------|------|---------| | v1.0 | 2026-04-09 | 初始版本，完整功能发布 | --- ## 11. 联系方式 - **作者：** 虾哥 - **邮箱：** anonymous@linuxacme.com - **项目地址：** https://git.linuxacme.com/iorebuild/VoiletCStudio.git --- **文档版本：** v1.0 **最后更新：** 2026-04-09