iorebuild/VoiletCStudio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

添加需求规格说明书和完整文档

Browse Source
This commit is contained in:
虾哥
2026-04-09 10:20:17 -04:00
parent 19296b7337
commit 7c81d53b3a
1 changed files with 540 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

540
需求规格说明书.md Normal file
View File

@@ -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