`.vcxproj` 및 `.props` 파일 구조

아티클
10/12/2023

MSBuild는 Visual Studio의 기본 프로젝트 시스템입니다. Visual C++에서 새 파일>프로젝트를 선택하면 확장.vcxproj명이 있는 XML 프로젝트 파일에 설정이 저장된 MSBuild 프로젝트를 만듭니다. 프로젝트 파일은 설정을 저장할 수 있는 파일과 .targets 파일을 가져올 .props 수도 있습니다.

IDE에서 프로젝트 속성을 기본하려는 경우 IDE에서만 프로젝트를 만들고 수정 .vcxproj 하고 파일에 대한 수동 편집을 방지하는 것이 좋습니다. 대부분의 경우 프로젝트 파일을 수동으로 편집할 필요가 없습니다. 수동으로 편집하면 Visual Studio 속성 페이지에서 프로젝트 설정을 수정하는 데 필요한 프로젝트 연결이 끊어질 수 있으며 디버그 및 복구하기 어려운 빌드 오류가 발생할 수 있습니다. 속성 페이지 사용에 대한 자세한 내용은 Visual Studio에서 C++ 컴파일러 설정 및 빌드 속성을 참조 하세요.

대규모로 IDE에서 많은 개별 프로젝트를 관리하는 것은 지루하고 오류가 발생하기 쉽습니다. 수십 또는 수백 개의 프로젝트에서 일관성을 기본 표준화를 적용하기는 어렵습니다. 이러한 경우 여러 프로젝트에서 공통 속성에 대해 사용자 지정 .props 또는 .targets 파일을 사용하도록 프로젝트 파일을 편집하는 것이 좋습니다. IDE에서 사용할 수 없는 사용자 지정이 필요한 경우에도 이러한 파일을 사용할 수 있습니다. 사용자 지정을 삽입하는 편리한 위치는 Directory.Build.props 모든 MSBuild 기반 프로젝트에서 자동으로 가져오는 파일 및 Directory.Build.targets 파일입니다.

경우에 따라 사용자 지정 .props 또는 .targets 파일만으로는 프로젝트 관리 요구 사항에 충분하지 않을 수 있습니다. 프로젝트 파일 또는 속성 시트를 수동으로 수정 .vcxproj 해야 할 수도 있습니다. 수동으로 편집하려면 MSBuild를 잘 이해해야 하며 이 문서의 지침을 따라야 합니다. IDE가 파일을 자동으로 로드하고 업데이트 .vcxproj 하기 위해 이러한 파일에는 다른 MSBuild 프로젝트 파일에 적용되지 않는 몇 가지 제한 사항이 있습니다. 실수로 인해 IDE가 예기치 않은 방식으로 충돌하거나 동작할 수 있습니다.

수동 편집 시나리오의 경우 이 문서에는 파일의 .vcxproj 구조 및 관련 파일에 대한 기본 정보가 포함되어 있습니다.

중요 사항

파일을 수동으로 편집 .vcxproj 하도록 선택하는 경우 다음 사실을 알고 있어야 합니다.

파일의 구조는 이 문서에서 설명하는 규정된 양식을 따라야 합니다.
Visual Studio C++ 프로젝트 시스템은 현재 프로젝트 항목에서 직접 야생카드 또는 목록을 지원하지 않습니다. 예를 들어 이러한 양식은 지원되지 않습니다.
```
<ItemGroup>
   <None Include="*.txt"/>
   <ClCompile Include="a.cpp;b.cpp"/>
</ItemGroup>
```
프로젝트의 wild카드 지원 및 가능한 해결 방법에 대한 자세한 내용은 파일 및 야생 카드 참조 .vcxproj 하세요.
Visual Studio C++ 프로젝트 시스템은 현재 프로젝트 항목 경로의 매크로를 지원하지 않습니다. 예를 들어 이 양식은 지원되지 않습니다.
```
<ItemGroup>
   <ClCompile Include="$(IntDir)\generated.cpp"/>
</ItemGroup>
```
"지원되지 않음"은 매크로가 IDE의 모든 작업에 대해 작동하도록 보장되지 않음을 의미합니다. 다른 구성에서 해당 값을 변경하지 않는 매크로는 작동하지만 항목이 다른 필터 또는 프로젝트로 이동된 경우에는 유지되지 않을 수 있습니다. 다른 구성에 대한 값을 변경하는 매크로는 문제를 발생시킬 수 있습니다. IDE는 프로젝트 구성에 따라 프로젝트 항목 경로가 다를 것으로 예상하지 않습니다.
프로젝트 속성 대화 상자에서 프로젝트 속성을 편집할 때 프로젝트 속성을 올바르게 추가, 제거 또는 수정하려면 파일에 각 프로젝트 구성에 대해 별도의 그룹이 포함되어야 합니다. 조건은 다음 형식이어야 합니다.
```
Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"
```
각 속성은 속성 규칙 파일에 지정된 대로 올바른 레이블을 사용하여 그룹에 지정해야 합니다. 자세한 내용은 속성 페이지 xml 규칙 파일을 참조하세요.

`.vcxproj` 파일 요소

텍스트 또는 XML 편집기를 사용하여 파일의 .vcxproj 내용을 검사할 수 있습니다. 솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭하고, 프로젝트 언로드를 선택한 다음, Foo.vcxproj 편집을 선택하여 Visual Studio에서 볼 수 있습니다.

가장 먼저 주목해야 할 것은 최상위 요소가 특정 순서로 표시된다는 것입니다. 예시:

대부분의 속성 그룹 및 항목 정의 그룹은 Microsoft.Cpp.Default.props를 가져온 후에 표시됩니다.
모든 대상은 파일의 끝에서 가져옵니다.
각각 고유한 레이블이 있는 여러 속성 그룹이 있으며 특정 순서로 표시됩니다.

MSBuild는 순차적 평가 모델을 기반으로 하기 때문에 프로젝트 파일의 요소 순서는 매우 중요합니다. 가져온 .props 모든 파일과 .targets 파일을 포함한 프로젝트 파일이 속성의 여러 정의로 구성된 경우 마지막 정의는 이전 정의를 재정의합니다. 다음 예제에서는 MSBUild 엔진이 평가 중에 마지막으로 발견되므로 컴파일 중에 "xyz" 값이 설정됩니다.

  <MyProperty>abc</MyProperty>
  <MyProperty>xyz</MyProperty>

다음 코드 조각에는 최소 .vcxproj 파일이 나와 있습니다. Visual Studio에서 생성된 모든 .vcxproj 파일에는 이러한 최상위 MSBuild 요소가 포함됩니다. 또한 이러한 각 최상위 요소의 복사본이 여러 개 포함될 수 있지만 이 순서대로 표시됩니다. 모든 Label 특성은 편집을 위한 기호로만 Visual Studio에서 사용되는 임의의 태그이며 다른 함수는 없습니다.

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003'>
  <ItemGroup Label="ProjectConfigurations" />
  <PropertyGroup Label="Globals" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
  <PropertyGroup Label="Configuration" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
  <ImportGroup Label="ExtensionSettings" />
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
  <ImportGroup Label="ExtensionTargets" />
</Project>

다음 섹션에서는 이러한 각 요소의 목적과 이러한 요소의 순서가 이러한 방식으로 정렬되는 이유를 설명합니다.

프로젝트 요소

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003' >

Project는 루트 노드입니다. 사용할 MSBuild 버전과 이 파일이 MSBuild.exe에 전달될 때 실행할 기본 대상도 지정합니다.

ProjectConfigurations ItemGroup 요소

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations에는 프로젝트 구성 설명이 포함됩니다. 예를 들어 디버그|Win32, 릴리스|Win32, 디버그|ARM 등등입니다. 많은 프로젝트 설정은 지정된 구성에 따라 다릅니다. 예를 들어 릴리스 빌드에 대한 최적화 속성을 설정하려고 하지만 디버그 빌드는 설정하지 않을 수 있습니다.

ProjectConfigurations 항목 그룹은 빌드 시 사용되지 않습니다. Visual Studio IDE를 사용하려면 프로젝트를 로드해야 합니다. 이 항목 그룹을 파일로 .props 이동하고 파일로 가져올 .vcxproj 수 있습니다. 그러나 이 경우 구성을 추가하거나 제거해야 하는 경우 파일을 수동으로 편집 .props 해야 하며 IDE를 사용할 수 없습니다.

ProjectConfiguration 요소

다음 코드 조각에서는 프로젝트 구성을 보여 줍니다. 이 예제에서 'Debug|x64'는 구성 이름입니다. 프로젝트 구성 이름은 형식 $(Configuration)|$(Platform)이어야 합니다. 노드에는 ProjectConfiguration 두 가지 속성이 Platform있을 수 있습니다. Configuration 이러한 속성은 구성이 활성 상태일 때 여기에 지정된 값으로 자동으로 설정됩니다.

<ProjectConfiguration Include="Debug|x64">
  <Configuration>Debug</Configuration>
  <Platform>x64</Platform>
</ProjectConfiguration>

IDE는 모든 ProjectConfiguration 항목에 사용되는 값의 Configuration 조합에 Platform 대한 프로젝트 구성을 찾아야 합니다. 종종 이 요구 사항을 충족하기 위해 프로젝트에 의미 없는 프로젝트 구성이 있을 수 있음을 의미합니다. 예를 들어 프로젝트에 다음 구성이 있는 경우가 있습니다.

디버그|Win32
소매|Win32
특별한 32비트 최적화|Win32

그렇다면 "특별한 32비트 최적화"가 x64에는 의미가 없더라도 다음과 같은 구성이 있어야 합니다.

Debug|x64
소매|x64
특별한 32비트 최적화|x64

솔루션 구성 관리자에서 모든 구성에 대한 빌드 및 배포 명령을 사용하지 않도록 설정할 수 있습니다.

Globals PropertyGroup 요소

<PropertyGroup Label="Globals" />

Globals 에는 프로젝트 수준 설정(예: ProjectGuid, RootNamespace또는 ApplicationTypeApplicationTypeRevision.)이 포함됩니다. 마지막 두 설정에서 대상 OS를 정의하는 경우가 있습니다. 현재 참조 및 프로젝트 항목에는 조건이 없으므로 프로젝트는 단일 OS만 대상으로 지정할 수 있습니다. 이러한 속성은 일반적으로 프로젝트 파일의 다른 위치에서 재정의되지 않습니다. 이 그룹은 구성에 종속되지 않으며 일반적으로 프로젝트 파일에 하나의 Globals 그룹만 존재합니다.

Microsoft.Cpp.default.props Import 요소

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />

Microsoft.Cpp.default.props 속성 시트는 Visual Studio와 함께 제공되며 수정할 수 없습니다. 여기에는 프로젝트에 대한 기본 설정이 포함됩니다. 기본값은 ApplicationType에 따라 달라질 수 있습니다.

Configuration PropertyGroup 요소

<PropertyGroup Label="Configuration" />

Configuration 속성 그룹에는 연결된 구성 조건(예: Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'")이 있으며 구성별로 하나씩 여러 복사본이 제공됩니다. 이 속성 그룹은 특정 구성에 대해 설정된 속성을 호스팅합니다. Configuration 속성에는 PlatformToolset이 포함되며, Microsoft.Cpp.props의 시스템 속성 시트 포함 여부를 제어합니다. 예를 들어 <CharacterSet>Unicode</CharacterSet> 속성을 정의하면 microsoft.Cpp.unicodesupport.props 시스템 속성 시트가 포함됩니다. Microsoft.Cpp.props를 검사하면 다음 줄<Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />이 표시됩니다.

Microsoft.Cpp.props Import 요소

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />

Microsoft.Cpp.props 속성 시트(직접 또는 가져오기를 통해)는 많은 도구별 속성에 대한 기본값을 정의합니다. 예를 들어 컴파일러의 최적화 및 경고 수준 속성, MIDL 도구의 TypeLibraryName 속성 등이 있습니다. 또한 바로 앞에 속성 그룹에 정의된 구성 속성에 따라 다양한 시스템 속성 시트를 가져옵니다.

ExtensionSettings ImportGroup 요소

<ImportGroup Label="ExtensionSettings" />

ExtensionSettings 그룹에는 빌드 사용자 지정에 속한 속성 시트에 대한 가져오기가 포함됩니다. 빌드 사용자 지정은 파일, 파일 및 .xml 파일 .targets 의 최대 3개 파일로 .props 정의됩니다. 이 가져오기 그룹에는 파일에 대한 가져오기가 .props 포함됩니다.

PropertySheets ImportGroup 요소

<ImportGroup Label="PropertySheets" />

PropertySheets 그룹에는 사용자 속성 시트에 대한 가져오기가 포함됩니다. 이러한 가져오기는 Visual Studio의 속성 관리자 보기를 통해 추가하는 속성 시트입니다. 이러한 가져오기가 나열되는 순서는 중요하며 속성 관리자에 반영됩니다. 프로젝트 파일에는 일반적으로 각 프로젝트 구성마다 하나씩 이러한 종류의 가져오기 그룹에 대한 여러 인스턴스가 포함됩니다.

UserMacros PropertyGroup 요소

<PropertyGroup Label="UserMacros" />

UserMacros에는 빌드 프로세스를 사용자 지정하는 데 사용되는 변수로 만든 속성이 포함됩니다. 예를 들어 사용자 지정 출력 경로를 $(CustomOutputPath)로 정의하는 사용자 매크로를 정의하고, 이를 사용하여 다른 변수를 정의할 수 있습니다. 이 속성 그룹에는 이러한 속성이 보관됩니다. Visual C++는 구성에 대한 사용자 매크로를 지원하지 않으므로 Visual Studio에서 이 그룹은 프로젝트 파일에 채워지지 않습니다. 사용자 매크로는 속성 시트에서 지원됩니다.

구성별 PropertyGroup 요소

<PropertyGroup />

이 속성 그룹에는 모든 프로젝트 구성에 대해 구성별로 하나씩 여러 개의 인스턴스가 있습니다. 각 속성 그룹은 하나의 구성 조건에 연결되어야 합니다. 누락된 구성이 있으면 프로젝트 속성 대화 상자가 올바르게 작동하지 않습니다. 이전에 나열된 속성 그룹과 달리 이 그룹에는 레이블이 없습니다. 이 그룹에는 프로젝트 구성 수준 설정이 포함됩니다. 이러한 설정은 지정된 항목 그룹에 속한 모든 파일에 적용됩니다. 빌드 사용자 지정 항목 정의 메타데이터는 여기서 초기화됩니다.

이 PropertyGroup은 이후에 와 <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> 야 하며 레이블이 없으면 다른 PropertyGroup이 없어야 합니다(그렇지 않으면 프로젝트 속성 편집이 제대로 작동하지 않음).

구성별 ItemDefinitionGroup 요소

<ItemDefinitionGroup />

항목 정의가 포함됩니다. 이러한 정의는 레이블이 없는 구성 PropertyGroup 요소와 동일한 조건 규칙을 따라야 합니다.

ItemGroup 요소

<ItemGroup />

ItemGroup 요소는 프로젝트의 항목(원본 파일 등)을 포함합니다. 조건은 프로젝트 항목(즉, 규칙 정의에 의해 프로젝트 항목으로 처리되는 항목 형식)에 대해 지원되지 않습니다.

메타데이터는 모두 동일한 경우에도 각 구성에 대한 구성 조건이 있어야 합니다. 예시:

<ItemGroup>
  <ClCompile Include="stdafx.cpp">
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</TreatWarningAsError>
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</TreatWarningAsError>
  </ClCompile>
</ItemGroup>

Visual Studio C++ 프로젝트 시스템은 현재 프로젝트 항목에서 야생 카드 지원하지 않습니다.

<ItemGroup>
  <ClCompile Include="*.cpp"> <!--Error-->
</ItemGroup>

Visual Studio C++ 프로젝트 시스템은 현재 프로젝트 항목의 매크로를 지원하지 않습니다.

<ItemGroup>
  <ClCompile Include="$(IntDir)\generated.cpp"> <!--not guaranteed to work in all scenarios-->
</ItemGroup>

참조는 ItemGroup에 지정되며, 제한 사항은 다음과 같습니다.

참조는 조건을 지원하지 않습니다.
참조 메타데이터는 조건을 지원하지 않습니다.

Microsoft.Cpp.targets Import 요소

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />

빌드, 클린 등과 같은 C++ 대상을 직접 또는 가져오기를 통해 정의합니다.

ExtensionTargets ImportGroup 요소

<ImportGroup Label="ExtensionTargets" />

이 그룹에는 빌드 사용자 지정 대상 파일에 대한 가져오기가 포함됩니다.

잘못된 순서의 결과

Visual Studio IDE는 이전에 설명한 순서가 있는 프로젝트 파일에 따라 달라집니다. 예를 들어 속성 페이지에서 속성 값을 정의하면 IDE는 일반적으로 빈 레이블이 있는 속성 그룹에 속성 정의를 배치합니다. 이 순서를 지정하면 시스템 속성 시트에 가져온 기본값이 사용자 정의 값으로 재정의됩니다. 마찬가지로 대상 파일은 이전에 정의된 속성을 사용하고 일반적으로 속성 자체를 정의하지 않으므로 마지막에 가져옵니다. 마찬가지로 사용자 속성 시트는 시스템 속성 시트(포함 Microsoft.Cpp.props됨) 후에 가져옵니다. 이 순서는 사용자가 시스템 속성 시트에서 가져온 모든 기본값을 재정의할 수 있도록 합니다.

파일이 이 레이아웃을 .vcxproj 따르지 않으면 빌드 결과가 예상과 다를 수 있습니다. 예를 들어 사용자가 정의한 속성 시트 뒤의 시스템 속성 시트를 실수로 가져오는 경우 사용자 설정은 시스템 속성 시트에 의해 재정의됩니다.

IDE 디자인 타임 환경도 요소의 올바른 순서에 따라 어느 정도 달라집니다. 예를 들어 파일에 가져오기 그룹이 없는 PropertySheets 경우 .vcxproj IDE는 사용자가 속성 관리자에서 만든 새 속성 시트를 배치할 위치를 결정하지 못할 수 있습니다. 이로 인해 사용자 시트가 시스템 시트로 재정의될 수 있습니다. IDE에서 사용하는 추론은 파일 레이아웃에서 사소한 불일치 .vcxproj 를 허용할 수 있지만 이 문서의 앞부분에 표시된 구조에서 벗어나지 않는 것이 좋습니다.

IDE에서 요소 레이블을 사용하는 방법

IDE에서 일반 속성 페이지에서 UseOfAtl 속성을 설정하면 프로젝트 파일의 Configuration 속성 그룹에 기록됩니다. 동일한 속성 페이지의 TargetName 속성은 레이블이 없는 구성별 속성 그룹에 기록됩니다. Visual Studio에서는 속성 페이지의 xml 파일에서 각 속성을 작성할 위치에 대한 정보를 찾습니다. 일반 속성 페이지의 경우 Visual Studio 2019 Enterprise Edition의 영어 버전이 있다고 가정하면 해당 파일은 다음과 입니다%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. 속성 페이지 XML 규칙 파일은 규칙 및 관련된 모든 속성에 대한 정적 정보를 정의합니다. 이러한 정보 중 하나는 대상 파일(해당 값이 작성된 파일)의 Rule 속성에 대한 기본 설정 위치입니다. 기본 설정 위치는 프로젝트 파일 요소의 Label 특성으로 지정됩니다.

속성 시트 레이아웃

다음 XML 코드 조각은 최소한의 속성 시트(.props) 파일 레이아웃입니다. 파일과 유사 .vcxproj 하며 요소의 .props 기능은 이전 설명에서 유추할 수 있습니다.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
</Project>

사용자 고유의 속성 시트를 만들려면 폴더에 .props 있는 VCTargets 파일 중 하나를 복사하여 사용자 용도로 수정합니다. Visual Studio 2019 Enterprise Edition의 경우 기본 VCTargets 경로는 .입니다 %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.

참고 항목

Visual Studio에서 C++ 컴파일러 및 빌드 속성 설정
속성 페이지 XML 파일
.vcxproj 파일 및 와일드카드

`.vcxproj` 및 `.props` 파일 구조

중요 사항

`.vcxproj` 파일 요소

프로젝트 요소

ProjectConfigurations ItemGroup 요소

ProjectConfiguration 요소

Globals PropertyGroup 요소

Microsoft.Cpp.default.props Import 요소

Configuration PropertyGroup 요소

Microsoft.Cpp.props Import 요소

ExtensionSettings ImportGroup 요소

PropertySheets ImportGroup 요소

UserMacros PropertyGroup 요소

구성별 PropertyGroup 요소

구성별 ItemDefinitionGroup 요소

ItemGroup 요소

Microsoft.Cpp.targets Import 요소

ExtensionTargets ImportGroup 요소

잘못된 순서의 결과

IDE에서 요소 레이블을 사용하는 방법

속성 시트 레이아웃

참고 항목

피드백

피드백

추가 리소스

.vcxproj 및 .props 파일 구조

중요 사항

.vcxproj 파일 요소

프로젝트 요소

ProjectConfigurations ItemGroup 요소

ProjectConfiguration 요소

Globals PropertyGroup 요소

Microsoft.Cpp.default.props Import 요소

Configuration PropertyGroup 요소

Microsoft.Cpp.props Import 요소

ExtensionSettings ImportGroup 요소

PropertySheets ImportGroup 요소

UserMacros PropertyGroup 요소

구성별 PropertyGroup 요소

구성별 ItemDefinitionGroup 요소

ItemGroup 요소

Microsoft.Cpp.targets Import 요소

ExtensionTargets ImportGroup 요소

잘못된 순서의 결과

IDE에서 요소 레이블을 사용하는 방법

속성 시트 레이아웃

참고 항목

피드백

피드백

추가 리소스

`.vcxproj` 및 `.props` 파일 구조

`.vcxproj` 파일 요소