# props

**Repository Path**: arhunn/props

## Basic Information

- **Project Name**: props
- **Description**: vs properties document
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-23
- **Last Updated**: 2025-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# C++ 项目构建系统标准作业程序 (SOP)

**版本: 1.0**
**最后更新时间: 2025-08-23**

## 1. 概述

### 1.1. 目的
本文档旨在规范化C++项目的Visual Studio构建环境，通过将构建配置与源代码分离，实现构建逻辑的**版本化**、**模块化**与**可复用性**。本规范旨在提升项目可维护性、降低团队协作成本，并为未来向CMake等跨平台构建系统的迁移奠定坚实基础。

### 1.2. 核心思想
- **构建配置中心化**：所有通用的构建逻辑（编译器选项、链接器选项、输出路径等）集中存放在一个独立的Git仓库中（`props`）。
- **Git Submodule集成**：主项目通过Git Submodule机制引入并锁定特定版本的构建配置。
- **自动化加载**：利用MSBuild的`Directory.Build.props`机制，实现构建配置的自动加载，无需手动修改每个项目文件。
- **关注点分离**：项目文件（`.vcxproj`）只关心其包含的源文件，业务源代码与构建系统文件物理分离。

### 1.3. 适用范围
本文档适用于所有使用Visual Studio作为主要IDE的C++项目。

## 2. 规范与定义

### 2.1. 目录结构规范
所有项目必须遵循以下标准目录结构：

```
YourSolutionRoot/
|
|-- .git/                       # 主项目的Git元数据
|-- .gitignore                  # 全局Git忽略文件
|-- .gitmodules                 # Git Submodule配置文件
|-- Directory.Build.props       # 【引导文件】用于加载Submodule中的构建配置
|
|-- build/                      # 【构建产物】所有编译和链接的输出，此目录由.gitignore忽略
|
|-- props/                      # 【Git Submodule】指向公司统一的构建配置仓库
|   |-- Directory.Build.props   #   (真正的核心配置文件)
|   |-- Configurations.props
|   |-- Global.props
|   |-- Compiler.props
|   |-- Linker.props
|   |-- Output.props
|   |-- README.md
|
|-- solution/                   # 【VS项目文件】存放所有.sln, .vcxproj, .vcxproj.filters文件
|   |-- YourSolution.sln
|   |-- project1.vcxproj
|   |-- project1.vcxproj.filters
|   |-- project1.props          #   (项目专属属性)
|   |-- ...
|
|-- src/                        # 【项目源代码】存放所有业务逻辑代码
|   |-- project1/
|   |   |-- include/
|   |   |-- src/
|   |-- ...
|
|-- 3rdParty/                   # 【第三方库】存放所有第三方库的源代码
|   |-- spdlog/
|   |   |-- spdlog.props        #   (spdlog专属的属性表)
|   |-- ...
|
|-- docs/                       # 【文档】存放项目相关文档
|-- README.md                   # 主项目说明文件
```


### 2.2. 文件职责定义 (已更新)

| 文件路径 | 职责 | 修改频率 |
| :--- | :--- | :--- |
| `/Directory.Build.props` | **引导文件 (Bootstrapper)**。唯一作用是加载`props/Directory.Build.props`。通常不需修改。 | 极低 |
| `props/Directory.Build.props` | **配置枢纽 (Configuration Hub)**。**职责已扩展：**<br>1. 定义所有基础路径变量（`SolutionRoot`, `BuildOutputRoot`等）。<br>2. **定义最核心的平台属性（`PlatformToolset`, `WindowsTargetPlatformVersion`）和项目类型（`ConfigurationType`），确保它们在VS默认属性表之前生效。**<br>3. 作为属性系统的入口，导入`Global.props`。 | 低 |
| `props/Global.props` | **全局调度中心 (Dispatcher)**。**职责更聚焦：**<br>1. 定义全局元数据（如`SolutionVersion`, `Copyright`）。<br>2. 定义辅助变量（如`PlatformShortName`）。<br>3. **调度导入**其他功能单一的属性表（`Configurations.props`, `Output.props`, `Compiler.props`, `Linker.props`等）。 | 低 |
| `props/Output.props` | **输出路径专家**。统一管理所有中间文件（obj）和最终产物（bin/lib/exe）的输出路径及命名规则（`IntDir`, `OutDir`, `TargetName`）。 | 低 |
| `props/Compiler.props` | **编译器管家**。统一管理所有项目的编译器设置（警告级别、C++标准、宏定义等）。 | 中 |
| `props/Linker.props` | **链接器专家**。统一管理所有项目的链接器设置（库目录、依赖项等）。 | 中 |
| `solution/*.vcxproj` | **项目定义文件**。只负责定义项目包含的源文件、头文件，以及项目专属的属性表导入（如第三方库的`.props`）。 | 高 |
| `solution/*.vcxproj.filters` | **IDE视图文件**。负责在Visual Studio的Solution Explorer中组织文件的逻辑视图。 | 高 |
| `solution/*.props` (可选) | **项目专属属性**。定义特定项目独有的配置（如特殊的宏定义、专用的头文件目录等）。 | 中 |


## 3. 标准作业程序 (SOP)

### 3.1. 环境搭建：初始化一个新项目

此流程仅在创建全新解决方案时执行一次。

1.  **创建主项目Git仓库**
    - 在Git服务器上创建项目仓库。
    - 在本地克隆空仓库：`git clone <your-repo-url> YourSolutionRoot`
    - `cd YourSolutionRoot`

2.  **添加`props`子模块**
    - 执行命令：`git submodule add <company-build-props-repo-url> props`
    - 这将创建`props`目录并从远程拉取构建配置。

3.  **创建引导文件**
    - 在项目根目录 (`YourSolutionRoot/`) 创建文件 `Directory.Build.props`。
    - 填入内容 (参考附录 A.1)。

4.  **创建`.gitignore`文件**
    - 在项目根目录创建`.gitignore`文件。
    - 至少包含以下内容，以忽略构建产物和用户特定的IDE文件：
      ```gitignore
      # Visual Studio
      .vs/
      *.suo
      *.user
      *.sln.docstates

      # Build output
      [Bb]uild/
      [Dd]ebug/
      [Rr]elease/
      x64/
      Win32/
      *.obj
      *.pdb
      *.ilk
      *.exe
      *.dll
      *.lib
      *.tlog
      *.log

      # Other
      *~
      ```

5.  **创建其他目录**
    - 手动创建 `solution/`, `src/`, `3rdParty/`, `docs/` 目录。

6.  **创建Visual Studio解决方案**
    - 打开Visual Studio，选择 "Create a new project" -> "Blank Solution"。
    - **位置**：选择 `YourSolutionRoot/solution/` 目录。
    - **名称**：`YourSolution`。

7.  **首次提交**
    - `git add .`
    - `git commit -m "Initial project structure setup"`
    - `git push`

### 3.2. 日常开发：克隆现有项目

所有团队成员加入项目时执行此流程。

1.  **克隆主仓库并初始化子模块**
    ```bash
    git clone --recurse-submodules <your-repo-url>
    ```
    如果已经克隆但忘记了 `--recurse-submodules`，则执行：
    ```bash
    cd <your-repo-directory>
    git submodule update --init --recursive
    ```

2.  **打开解决方案**
    - 直接双击 `solution/YourSolution.sln` 文件即可开始工作。

### 3.3. 日常开发：添加一个新项目 (例如 `libutils`)

1.  **在VS中创建项目**
    - 在Solution Explorer中，右键点击解决方案 -> "Add" -> "New Project..."。
    - 选择项目模板（如 Static Library）。
    - **项目名称**：`libutils`。
    - **位置**：确保是 `YourSolutionRoot/solution/`。

2.  **创建源代码目录**
    - 在 `src/` 目录下创建 `libutils/` 文件夹，并内部创建 `include/` 和 `src/` 子目录。
    - 将源代码文件（如 `utility.h`, `utility.cpp`）放入相应目录。

3.  **(可选) 创建项目专属属性表**
    - 如果 `libutils` 有特殊配置（如专属宏），在 `solution/` 目录下创建 `libutils.props` 文件。
    - 示例内容 `solution/libutils.props`:
      ```xml
      <?xml version="1.0" encoding="utf-8"?>
      <Project>
        <ItemDefinitionGroup>
          <ClCompile>
            <!-- libutils 专属的宏定义 -->
            <PreprocessorDefinitions>LIBUTILS_STATIC;%(PreprocessorDefinitions)</PreprocessorDefinitions>
          </ClCompile>
        </ItemDefinitionGroup>
      </Project>
      ```

4.  **清理并配置`.vcxproj`文件**
    - 用文本编辑器打开 `solution/libutils.vcxproj`。
    - **删除所有`<PropertyGroup>`和`<ItemDefinitionGroup>`**，因为它们已由通用属性表管理。
    - 确保文件结构简洁，使用我们定义的路径变量引用源文件 (参考附录 A.4)。

5.  **配置`.vcxproj.filters`文件**
    - 为了在IDE中获得正确的目录视图，用文本编辑器打开 `solution/libutils.vcxproj.filters`，手动编辑使其逻辑路径与 `src/libutils/` 下的物理路径匹配。

6.  **提交变更**
    - 将新创建的文件 (`.vcxproj`, `.filters`, `.props`, 源代码) 添加到Git并提交。

### 3.4. 维护：更新通用构建配置

当需要全局修改构建规则时（如升级C++标准）。

1.  **进入`props`子模块目录**
    - `cd props`
2.  **切换到开发分支 (推荐)**
    - `git checkout -b feature/update-cpp-standard`
3.  **修改配置**
    - 编辑 `Compiler.props` 或其他相关文件。例如，将 `<LanguageStandard>stdcpp20</LanguageStandard>` 改为 `<LanguageStandard>stdcpp23</LanguageStandard>`。
4.  **提交并推送变更**到`props`仓库
    - `git add .`
    - `git commit -m "Feat: Upgrade C++ standard to C++23"`
    - `git push -u origin feature/update-cpp-standard`
    - （通过Pull Request等流程合并到`props`仓库的主分支）
5.  **在主项目中应用更新**
    - 回到主项目根目录: `cd ..`
    - 更新子模块以指向最新的commit: `git submodule update --remote --merge`
    - 查看状态，你会看到 `props` 目录有新的提交待处理: `git status`
    - 提交此更新：
      ```bash
      git add props
      git commit -m "Chore: Update build system to latest version"
      git push
      ```

### 3.5. 解决方案配置管理

1.  **打开配置管理器** ("Build" -> "Configuration Manager...")。
2.  **清理/创建解决方案配置**，使其名称与 `props/Configurations.props` 中定义的保持一致（如 `debug_shared`, `release_static_md`）。
3.  **映射项目配置**：确保对于每个解决方案配置，所有项目都正确地映射到对应的项目配置和平台。

### 3.6. 高级用法：管理项目专属配置

在复杂解决方案中，并非所有项目都需要全部的构建配置。例如，一个纯静态库项目不需要“动态库(shared)”相关的配置。本节将介绍如何实现配置的按需加载。

1.  核心机制

我们通过定义一个名为 `$(ProjectConfigType)` 的MSBuild属性来控制项目所需的配置类型。
在 `props/Configurations.props` 中，使用 `Condition` 属性包裹不同配置的 `ItemGroup`。
支持的 `ProjectConfigType` 值包括：
- `StaticAndShared` (默认): 项目同时需要静态库和动态库配置。
- `StaticOnly`: 项目只需要静态库配置。
- `SharedOnly`: 项目只需要动态库配置。
    ```xml
    <!-- props/Configurations.props -->
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- 1. 定义默认的项目配置类型 -->
  <PropertyGroup>
    <ProjectConfigType Condition="'$(ProjectConfigType)' == ''">StaticAndShared</ProjectConfigType>
  </PropertyGroup>

  <!-- 2. 为“共享库 (shared)”配置创建专属 ItemGroup -->
  <ItemGroup Label="ProjectConfigurationsShared" Condition="'$(ProjectConfigType)' == 'StaticAndShared' Or '$(ProjectConfigType)' == 'SharedOnly'">
    <ProjectConfiguration Include="debug_shared|x64">
      <Configuration>debug_shared</Configuration>
      <Platform>x64</Platform>
    </ProjectConfiguration>
    <!-- ... 其他_shared配置 ... -->
  </ItemGroup>

  <!-- 3. 为“静态库 (static)”配置创建专属 ItemGroup -->
  <ItemGroup Label="ProjectConfigurationsStatic" Condition="'$(ProjectConfigType)' == 'StaticAndShared' Or '$(ProjectConfigType)' == 'StaticOnly'">
    <ProjectConfiguration Include="debug_static_md|x64">
      <Configuration>debug_static_md</Configuration>
      <Platform>x64</Platform>
    </ProjectConfiguration>
    <!-- ... 其他_static配置 ... -->
    </ItemGroup>
</Project>
```

2.  在特定项目的专属 `.props` 文件（如 `solution/lib_static_only.props`）中定义该变量。
    ```xml
    <!-- solution/lib_static_only.props -->
    <Project>
      <PropertyGroup>
        <ProjectConfigType>StaticOnly</ProjectConfigType>
      </PropertyGroup>
    </Project>
    ```
3.  在 `.vcxproj` 文件的顶部导入此专属 `.props` 文件。


---
## 4. 附录：核心文件示例

### A.1. `/Directory.Build.props` (引导文件)
```xml
<?xml version="1.0" encoding="utf-8"?>
<Project>
  <!--
    这是引导文件。它的唯一作用就是加载 props 子模块中的核心配置入口。
    不要在这里添加任何实际的构建逻辑，以避免循环依赖和混乱。
  -->
  <Import Project="$(MSBuildThisFileDirectory)props\Directory.Build.props" />
</Project>

### A.2. props/Directory.Build.props (配置枢纽)
```xml
<?xml version="1.0" encoding="utf-8"?>
<Project>
  <!-- 
    这是 props 子模块的核心入口文件，是所有配置的“枢纽”。
    它的职责是：
    1. 定义所有其他 .props 文件都会依赖的最基础的路径变量。
    2. 定义最核心的平台和项目类型属性，确保它们在VS默认属性表之前生效。
    3. 导入 Global.props，从而启动整个配置加载链。
  -->
  
  <!-- 步骤 1: 定义基础路径变量 (The Coordinate System) -->
  <PropertyGroup Label="Path.Settings">
    <PropsRoot>$(MSBuildThisFileDirectory)</PropsRoot>
    <SolutionRoot>$(PropsRoot)..\</SolutionRoot>
    <SolutionDir>$(SolutionRoot)solution\</SolutionDir>
    <SourceRoot>$(SolutionRoot)src\</SourceRoot>
    <ThirdPartyRoot>$(SolutionRoot)3rdParty\</ThirdPartyRoot>
    <BuildOutputRoot>$(SolutionRoot)build\</BuildOutputRoot>
  </PropertyGroup>

  <!-- 步骤 2: 定义核心平台和项目类型属性 (The Platform Foundation) -->
  <PropertyGroup Label="Globals.BeforeImport">
    <WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>
    <PlatformToolset>v143</PlatformToolset>
    <CharacterSet>Unicode</CharacterSet>
    
    <!-- 默认所有项目都是库 (Library)，应用程序项目需要在自己的 .props 中覆盖为 true -->
    <IsApplication Condition="'$(IsApplication)' == ''">false</IsApplication>

    <!-- 关键：健壮的、互斥的ConfigurationType定义 -->
    <ConfigurationType Condition="'$(IsApplication)' == 'true'">Application</ConfigurationType>
    <ConfigurationType Condition="'$(IsApplication)' != 'true' And $([System.String]::new('$(Configuration)').Contains('shared'))">DynamicLibrary</ConfigurationType>
    <ConfigurationType Condition="'$(IsApplication)' != 'true' And $([System.String]::new('$(Configuration)').Contains('static'))">StaticLibrary</ConfigurationType>
  </PropertyGroup>

  <!-- 步骤 3: 导入全局调度中心，启动配置链 (The Engine Start) -->
  <Import Project="$(PropsRoot)Global.props" />
</Project>
```

### A.3. props/Global.props (全局调度中心)
```xml
<?xml version="1.0" encoding="utf-8"?>
<Project>
  <!-- 
    这是全局调度中心。它的职责是按正确的顺序导入所有功能性的属性表。
    它已经被 props/Directory.Build.props 导入，所有基础路径和平台属性已经可用。
  -->

  <!-- 全局元数据 -->
  <PropertyGroup>
    <SolutionVersion>1.0.0.1</SolutionVersion>
    <Copyright>Copyright (c) 2025 Your Company</Copyright>
  </PropertyGroup>
  
  <!-- 辅助变量，用于简化路径构建等 -->
  <PropertyGroup Condition="'$(Platform)' == 'x86'">
    <PlatformShortName>Win32</PlatformShortName>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Platform)' == 'x64'">
    <PlatformShortName>x64</PlatformShortName>
  </PropertyGroup>

  <!-- 按顺序导入其他细分的属性表 -->
  <Import Project="$(PropsRoot)Configurations.props" />
  <Import Project="$(PropsRoot)Output.props" />
  <Import Project="$(PropsRoot)Compiler.props" />
  <Import Project="$(PropsRoot)Linker.props" />
  
  <!--
    注意：这里不再导入 Microsoft.Cpp.*.props！
    这些由 MSBuild 和 .vcxproj 文件在正确的时机自行处理。
  -->
</Project>
```

### A.4. solution/my_project.vcxproj (清理后的项目文件示例)
```xml
<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- 
    所有通用配置都已通过 Directory.Build.props 自动导入。
    这个文件只关心三件事：
    1. (可选) 导入项目专属或第三方库的 .props 文件。
    2. 定义项目全局标识 (GUID)。
    3. 列出项目包含的源文件。
  -->
  
  <!-- 1. 导入项目专属或第三方库的属性表 -->
  <Import Project="my_project.props" Condition="Exists('my_project.props')" />
  <Import Project="$(ThirdPartyRoot)spdlog\spdlog.props" Condition="Exists('$(ThirdPartyRoot)spdlog\spdlog.props')" />

  <!-- 2. 项目全局标识 -->
  <PropertyGroup Label="Globals">
    <ProjectGuid>{YOUR-UNIQUE-GUID-HERE}</ProjectGuid>
    <RootNamespace>my_project</RootNamespace>
  </PropertyGroup>
  
  <!-- 3. 项目源文件列表 -->
  <ItemGroup>
    <ClInclude Include="$(SourceRoot)my_project\include\header1.h" />
    <ClInclude Include="$(SourceRoot)my_project\include\header2.h" />
  </ItemGroup>
  <ItemGroup>
    <ClCompile Include="$(SourceRoot)my_project\src\main.cpp" />
    <ClCompile Include="$(SourceRoot)my_project\src\logic.cpp" />
  </ItemGroup>
  
  <!-- 导入MSBuild的标准构建目标 -->
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
  
  <!-- 不要在这里添加 <ItemDefinitionGroup> 或 <PropertyGroup> -->
</Project>
```