diff --git a/需求规格说明书.md b/需求规格说明书.md new file mode 100644 index 0000000..13fe80e --- /dev/null +++ b/需求规格说明书.md @@ -0,0 +1,540 @@ +# 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