{"id":39661163,"url":"https://github.com/innovationmech/cpp-template","last_synced_at":"2026-01-18T09:24:00.884Z","repository":{"id":307636716,"uuid":"1029468204","full_name":"innovationmech/cpp-template","owner":"innovationmech","description":"A comprehensive C++ project template demonstrating modern C++ development practices with CMake build system. ","archived":false,"fork":false,"pushed_at":"2025-08-01T10:28:30.000Z","size":216,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-01T10:52:11.653Z","etag":null,"topics":["cpp"],"latest_commit_sha":null,"homepage":"","language":"CMake","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/innovationmech.png","metadata":{"files":{"readme":"README-CN.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-31T05:15:42.000Z","updated_at":"2025-08-01T09:54:06.000Z","dependencies_parsed_at":"2025-08-01T11:10:45.271Z","dependency_job_id":null,"html_url":"https://github.com/innovationmech/cpp-template","commit_stats":null,"previous_names":["innovationmech/cpp-template"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/innovationmech/cpp-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innovationmech%2Fcpp-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innovationmech%2Fcpp-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innovationmech%2Fcpp-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innovationmech%2Fcpp-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/innovationmech","download_url":"https://codeload.github.com/innovationmech/cpp-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innovationmech%2Fcpp-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp"],"created_at":"2026-01-18T09:24:00.803Z","updated_at":"2026-01-18T09:24:00.869Z","avatar_url":"https://github.com/innovationmech.png","language":"CMake","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cpp-template\n\n一个综合的 C++ 项目模板，展示了使用 CMake 构建系统的现代 C++ 开发实践。此模板为 C++ 项目提供了一个坚实的基础，具有多种依赖管理策略、全面的测试和跨平台兼容性。\n\n## 目录\n\n- [特性](#特性)\n- [项目结构](#项目结构)\n- [先决条件](#先决条件)\n- [快速开始](#快速开始)\n- [依赖管理](#依赖管理)\n- [构建项目](#构建项目)\n- [测试](#测试)\n- [开发环境设置](#开发环境设置)\n- [自定义](#自定义)\n- [故障排除](#故障排除)\n- [贡献](#贡献)\n\n## 特性\n\n- **现代 C++ 标准**: C++17+ 并显式指定版本\n- **模块化架构**: 清晰的职责分离和分层结构\n- **多种依赖管理**: 支持 vcpkg、系统包、Git 子模块和手动依赖\n- **全面的测试**: Google Test 集成，包含单元测试和集成测试\n- **跨平台**: 在 macOS、Linux 和 Windows 上运行\n- **CMake 最佳实践**: 分层构建系统和自定义模块\n- **开发工具**: 代码格式化、静态分析和 IDE 集成\n\n## 项目结构\n\n```\ncpp-template/\n├── CMakeLists.txt              # 顶层构建配置\n├── CMakePresets.json           # CMake 预设，用于不同配置\n├── README.md                   # 此文档\n├── vcpkg.json                  # vcpkg 清单文件\n├── .gitmodules                 # Git 子模块配置\n├── scripts/\n│   └── setup-dev-env.sh        # 开发环境设置\n├── src/                        # 应用程序源代码\n│   ├── CMakeLists.txt\n│   ├── main.cpp                # 应用程序入口点\n│   └── modules/                # 应用程序模块\n│       ├── config_manager.cpp\n│       └── data_processor.cpp\n├── include/                    # 公共头文件\n│   └── cpp-template/\n│       ├── cpp-template.h      # 主公共头文件\n│       ├── core.h              # 核心功能\n│       └── utils.h             # 工具函数\n├── libs/                       # 内部项目库\n│   ├── CMakeLists.txt\n│   └── core/                   # 示例内部库\n│       ├── CMakeLists.txt\n│       ├── include/core/\n│       └── src/\n├── tests/                      # 单元和集成测试\n│   ├── CMakeLists.txt\n│   └── unit/\n│       ├── basic_test.cpp\n│       ├── core_test.cpp\n│       ├── utils_test.cpp\n│       └── integration_test.cpp\n├── third_party/                # 外部依赖项\n│   ├── CMakeLists.txt\n│   ├── manual/                 # 手动管理的依赖项\n│   │   └── mathutils/          # 示例手动依赖项\n│   └── submodules/             # Git 子模块依赖项\n└── cmake/                      # 自定义 CMake 模块\n    ├── CompilerOptions.cmake   # 编译器配置\n    ├── VcpkgHelpers.cmake      # vcpkg 集成工具\n    ├── FindCustomLib.cmake     # 示例查找模块\n    ├── VcpkgGuide.md          # vcpkg 使用文档\n    ├── GitSubmodulesGuide.md  # Git 子模块文档\n    ├── ManualDependenciesGuide.md # 手动依赖项文档\n    └── SystemPackagesGuide.md # 系统包文档\n```\n\n## 先决条件\n\n### 必需要求\n\n- **CMake 3.20 或更高版本**: 构建系统生成器\n- **C++17 兼容编译器**: GCC 7+、Clang 5+、MSVC 2017+ 或 Apple Clang 10+\n- **Git**: 版本控制和子模块管理\n\n### 平台特定要求\n\n#### macOS\n\n```bash\n# 安装 Xcode 命令行工具\nxcode-select --install\n\n# 安装 Homebrew（推荐）\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# 安装必要工具\nbrew install cmake git ninja\n```\n\n#### Ubuntu/Debian\n\n```bash\n# 更新软件包列表\nsudo apt update\n\n# 安装必要工具\nsudo apt install build-essential cmake git ninja-build pkg-config\n```\n\n#### Fedora/RHEL/CentOS\n\n```bash\n# 安装开发工具\nsudo dnf groupinstall \"Development Tools\"\nsudo dnf install cmake git ninja-build pkgconfig\n```\n\n#### Windows\n\n```powershell\n# 安装 Chocolatey（以管理员身份运行）\nSet-ExecutionPolicy Bypass -Scope Process -Force\n[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072\niex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))\n\n# 安装必要工具\nchoco install cmake git ninja visualstudio2022buildtools\n```\n\n## 快速开始\n\n### 1. 克隆仓库\n\n```bash\n# 使用子模块克隆\ngit clone --recurse-submodules https://github.com/your-username/cpp-template.git\ncd cpp-template\n\n# 或者分别克隆和初始化子模块\ngit clone https://github.com/your-username/cpp-template.git\ncd cpp-template\ngit submodule update --init --recursive\n```\n\n### 2. 设置开发环境\n\n```bash\n# 运行设置脚本（macOS/Linux）\n./scripts/setup-dev-env.sh\n\n# 或者手动安装依赖项（参见开发环境设置部分）\n```\n\n### 3. 构建项目\n\n```bash\n# 基本构建\ncmake -B build -S .\ncmake --build build\n\n# 或使用预设（如果可用）\ncmake --preset default\ncmake --build build\n```\n\n### 4. 运行测试\n\n```bash\n# 运行所有测试\ncmake --build build --target test\n\n# 或直接使用 ctest\ncd build\nctest --output-on-failure\n```\n\n### 5. 运行应用程序\n\n```bash\n# 运行示例应用程序\n./build/src/cpp-template\n```\n\n## 依赖管理\n\n此项目支持四种不同的依赖管理方法。您可以根据需要使用这些方法的任意组合。\n\n### 1. vcpkg（推荐）\n\nvcpkg 是一个 C++ 包管理器，为多个平台提供预构建库。\n\n#### 安装\n\n```bash\n# 克隆 vcpkg\ngit clone https://github.com/Microsoft/vcpkg.git\ncd vcpkg\n\n# 启动 vcpkg\n./bootstrap-vcpkg.sh  # Linux/macOS\n# 或者\n.\\bootstrap-vcpkg.bat  # Windows\n```\n\n#### 使用\n\n```bash\n# 使用 vcpkg 工具链配置\ncmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake\n\n# 构建项目\ncmake --build build\n```\n\n#### 添加依赖项\n\n编辑 `vcpkg.json` 来添加新依赖项：\n\n```json\n{\n  \"dependencies\": [\n    \"existing-package\",\n    \"new-package\",\n    {\n      \"name\": \"versioned-package\",\n      \"version\u003e=\": \"1.0.0\"\n    }\n  ]\n}\n```\n\n有关 vcpkg 的详细使用方法，请参见 [CMake/VcpkgGuide.md](cmake/VcpkgGuide.md)。\n\n### 2. 系统包管理器\n\n使用系统级包管理器来处理常见库。\n\n#### macOS (Homebrew)\n\n```bash\n# 安装常见的 C++ 库\nbrew install boost openssl zlib curl sqlite postgresql\n\n# 配置和构建\ncmake -B build -S .\ncmake --build build\n```\n\n#### Ubuntu/Debian\n\n```bash\n# 安装开发库\nsudo apt install libboost-all-dev libssl-dev zlib1g-dev libcurl4-openssl-dev libsqlite3-dev libpq-dev\n\n# 配置和构建\ncmake -B build -S .\ncmake --build build\n```\n\n有关系统包的详细使用方法，请参见 [CMake/SystemPackagesGuide.md](cmake/SystemPackagesGuide.md)。\n\n### 3. Git 子模块\n\n使用 Git 子模块来处理基于源代码的依赖项。\n\n```bash\n# 添加新的子模块\ngit submodule add https://github.com/nlohmann/json.git third_party/submodules/json\n\n# 更新所有子模块\ngit submodule update --remote --merge\n\n# 使用子模块构建\ncmake -B build -S .\ncmake --build build\n```\n\n有关子模块的详细使用方法，请参见 [CMake/GitSubmodulesGuide.md](cmake/GitSubmodulesGuide.md)。\n\n### 4. 手动依赖项\n\n将库直接放在 `third_party/manual/` 目录中。\n\n```bash\n# 添加手动依赖项\nmkdir -p third_party/manual/mylib\n# 将库文件复制到 third_party/manual/mylib/\n\n# 使用手动依赖项构建\ncmake -B build -S .\ncmake --build build\n```\n\n有关手动依赖项管理的详细信息，请参见 [CMake/ManualDependenciesGuide.md](cmake/ManualDependenciesGuide.md)。\n\n## 构建项目\n\n### 构建配置\n\n```bash\n# 调试构建（默认）\ncmake -B build -S . -DCMAKE_BUILD_TYPE=Debug\ncmake --build build\n\n# 发布构建\ncmake -B build -S . -DCMAKE_BUILD_TYPE=Release\ncmake --build build\n\n# 带调试信息的发布构建\ncmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo\ncmake --build build\n```\n\n### 构建选项\n\n```bash\n# 启用详细输出\ncmake --build build --verbose\n\n# 构建特定目标\ncmake --build build --target cpp-template\n\n# 并行构建\ncmake --build build --parallel 4\n```\n\n### CMake 预设（可选）\n\n如果配置了 `CMakePresets.json`：\n\n```bash\n# 列出可用的预设\ncmake --list-presets\n\n# 使用特定预设\ncmake --preset vcpkg-release\ncmake --build build\n```\n\n## 测试\n\n### 运行测试\n\n```bash\n# 运行所有测试\ncmake --build build --target test\n\n# 使用详细输出运行测试\ncd build\nctest --output-on-failure --verbose\n\n# 运行特定测试\nctest -R \"core_test\"\n\n# 并行运行测试\nctest --parallel 4\n```\n\n### 测试类别\n\n- **单元测试**: 独立测试单个组件\n- **集成测试**: 测试组件交互\n- **系统测试**: 测试完整应用程序功能\n\n### 添加新测试\n\n1. 在 `tests/unit/` 中创建测试文件\n2. 在 `tests/unit/CMakeLists.txt` 中添加测试\n3. 遵循 Google Test 约定\n\n示例:\n\n```cpp\n#include \u003cgtest/gtest.h\u003e\n#include \"your_component.h\"\n\nTEST(YourComponentTest, BasicFunctionality) {\n    // 测试实现\n    EXPECT_EQ(expected, actual);\n}\n```\n\n## 开发环境设置\n\n### 自动化设置\n\n使用提供的设置脚本：\n\n```bash\n# macOS/Linux\n./scripts/setup-dev-env.sh\n\n# Windows (PowerShell 作为管理员)\n.\\scripts\\setup-dev-env.ps1\n```\n\n### 手动设置\n\n#### macOS\n\n```bash\n# 安装 Homebrew\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# 安装开发工具\nbrew install cmake git ninja boost openssl@3 zlib curl sqlite postgresql\n\n# 安装 vcpkg（可选）\ngit clone https://github.com/Microsoft/vcpkg.git ~/vcpkg\n~/vcpkg/bootstrap-vcpkg.sh\n```\n\n#### Linux (Ubuntu/Debian)\n\n```bash\n# 更新软件包列表\nsudo apt update\n\n# 安装构建工具\nsudo apt install build-essential cmake git ninja-build pkg-config\n\n# 安装常见库\nsudo apt install libboost-all-dev libssl-dev zlib1g-dev libcurl4-openssl-dev libsqlite3-dev libpq-dev\n\n# 安装 vcpkg（可选）\ngit clone https://github.com/Microsoft/vcpkg.git ~/vcpkg\n~/vcpkg/bootstrap-vcpkg.sh\n```\n\n#### Windows\n\n```powershell\n# 安装 Chocolatey（作为管理员）\nSet-ExecutionPolicy Bypass -Scope Process -Force\n[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072\niex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))\n\n# 安装开发工具\nchoco install cmake git ninja visualstudio2022buildtools\n\n# 安装 vcpkg\ngit clone https://github.com/Microsoft/vcpkg.git C:\\vcpkg\nC:\\vcpkg\\bootstrap-vcpkg.bat\n```\n\n### IDE 配置\n\n#### Visual Studio Code\n\n安装推荐的扩展：\n\n- C/C++ Extension Pack\n- CMake Tools\n- GitLens\n\n#### CLion\n\nCLion 应该能自动检测 CMake 配置。\n\n#### Visual Studio\n\n在支持 CMake 的 Visual Studio 2019+ 中打开文件夹。\n\n## 自定义\n\n### 适应模板\n\n1. **重命名项目**: 更新 `CMakeLists.txt` 和 `vcpkg.json`\n2. **修改依赖项**: 编辑依赖配置文件\n3. **更新结构**: 根据需要重新组织目录\n4. **自定义构建**: 修改 CMake 配置\n\n### 添加新组件\n\n#### 内部库\n\n```bash\n# 创建新的库目录\nmkdir -p libs/newlib/{include/newlib,src}\n\n# 添加 CMakeLists.txt\n# 更新 libs/CMakeLists.txt 以包含新库\n```\n\n#### 应用程序模块\n\n```bash\n# 创建新模块\nmkdir -p src/modules/newmodule\n\n# 添加源文件并更新 src/modules/CMakeLists.txt\n```\n\n### 配置选项\n\n常见的自定义点：\n\n- **C++ 标准**: 在主 `CMakeLists.txt` 中更改\n- **编译器选项**: 修改 `cmake/CompilerOptions.cmake`\n- **依赖项**: 更新相应的配置文件\n- **测试**: 修改 `tests/CMakeLists.txt` 中的测试配置\n\n## 故障排除\n\n### 常见构建问题\n\n#### CMake 配置失败\n\n```bash\n# 清除 CMake 缓存\nrm -rf build/\ncmake -B build -S .\n```\n\n#### 未找到依赖项\n\n```bash\n# 检查依赖项是否已安装\n# 对于 vcpkg:\nvcpkg list\n\n# 对于系统包 (macOS):\nbrew list | grep package-name\n\n# 对于系统包 (Ubuntu):\ndpkg -l | grep package-name\n```\n\n#### 编译器错误\n\n```bash\n# 检查编译器版本\ngcc --version\nclang --version\n\n# 确保支持 C++17\ncmake -B build -S . -DCMAKE_CXX_STANDARD=17\n```\n\n### 平台特定问题\n\n#### macOS\n\n- **Xcode 命令行工具**: 运行 `xcode-select --install`\n- **Homebrew 权限**: `sudo chown -R $(whoami) /opt/homebrew`\n- **Apple Silicon**: 确保 ARM64 兼容性\n\n#### Linux\n\n- **缺少开发头文件**: 安装 `-dev` 软件包\n- **权限问题**: 使用 `sudo` 安装系统软件包\n- **编译器版本**: 确保 GCC 7+ 或 Clang 5+\n\n#### Windows\n\n- **Visual Studio 构建工具**: 大多数 C++ 包都需要\n- **PowerShell 执行策略**: `Set-ExecutionPolicy RemoteSigned`\n- **路径问题**: 安装后重启终端\n\n### 调试信息\n\n启用详细输出以进行调试：\n\n```bash\n# CMake 详细输出\ncmake -B build -S . --debug-output\n\n# 构建详细输出\ncmake --build build --verbose\n\n# 测试详细输出\ncd build \u0026\u0026 ctest --verbose\n```\n\n### 获取帮助\n\n1. **检查文档**: 查看 `cmake/` 目录中的指南\n2. **搜索问题**: 在项目问题中查找类似问题\n3. **启用调试输出**: 使用详细标志获取详细信息\n4. **检查依赖项**: 验证所有必需的依赖项是否已安装\n\n## 贡献\n\n### 开发工作流程\n\n1. Fork 仓库\n2. 创建功能分支\n3. 进行更改并添加测试\n4. 确保所有测试通过\n5. 提交拉取请求\n\n### 代码标准\n\n- 遵循 C++17 最佳实践\n- 使用一致的命名约定\n- 为新功能添加全面的测试\n- 记录公共 API\n- 遵循现有的代码风格\n\n### 测试要求\n\n- 所有新代码都必须有测试\n- 测试必须在所有支持的平台上通过\n- 为新功能添加集成测试\n- 为关键路径添加性能测试\n\n---\n\n此模板为 C++ 项目提供了一个坚实的基础。根据您的具体需求和要求自定义它。有关特定方面的详细信息，请参阅 `cmake/` 目录中的文档文件。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnovationmech%2Fcpp-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finnovationmech%2Fcpp-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnovationmech%2Fcpp-template/lists"}