Поделиться через

.vcxproj и .props структура файлов

  • Статья

MSBuild — это система проектов по умолчанию в Visual Studio. При выборе> файла нового проекта в Visual C++ вы создаете проект MSBuild, параметры которого хранятся в XML-файле проекта с расширением..vcxproj Файл проекта также может импортировать .props файлы и .targets файлы, где можно хранить параметры.

Если вы планируете поддерживать свойства проекта в интегрированной среде разработки, рекомендуется создавать и изменять .vcxproj проекты только в интегрированной среде разработки и избегать ручного редактирования файлов. В большинстве случаев вам никогда не нужно вручную редактировать файл проекта. Изменения вручную могут нарушить подключения к проекту, необходимые для изменения параметров проекта на страницах свойств Visual Studio, и могут привести к ошибкам сборки, которые трудно выполнить отладку и восстановление. Дополнительные сведения об использовании страниц свойств см. в разделе Set C++ компилятор и свойства сборки в Visual Studio.

В большом масштабе управление многими отдельными проектами в интегрированной среде разработки становится емким и подверженным ошибкам. Трудно поддерживать согласованность или применять стандартизацию в десятках или сотнях проектов. В этих случаях стоит изменить файлы проекта, чтобы использовать настраиваемые .props или .targets файлы для общих свойств во многих проектах. Эти файлы также можно использовать при необходимости настройки, которые недоступны в интегрированной среде разработки. Удобные места для вставки настроек — это Directory.Build.props и Directory.Build.targets файлы, которые автоматически импортируются во все проекты на основе MSBuild.

В некоторых случаях настройка .props или .targets файлы могут быть недостаточно для управления проектами. Возможно, вам потребуется вручную изменить .vcxproj файлы проекта или таблицы свойств. Редактирование вручную требует хорошего понимания MSBuild и должно соответствовать рекомендациям, приведенным в этой статье. Для автоматической загрузки и обновления .vcxproj файлов интегрированной среды разработки эти файлы имеют несколько ограничений, которые не применяются к другим файлам проекта MSBuild. Ошибки могут привести к сбою интегрированной среды разработки или вести себя непредвиденными способами.

В сценариях редактирования вручную эта статья содержит основные сведения о структуре и связанных файлах .vcxproj .

Важные замечания

Если вы решили вручную изменить .vcxproj файл, помните об этих фактах:

  • Структура файла должна соответствовать предписанной форме, которая описана в этой статье.

  • В настоящее время система проектов Visual Studio C++ не поддерживает подстановочные знаки или списки непосредственно в элементах проекта. Например, эти формы не поддерживаются:

    <ItemGroup>
   <None Include="*.txt"/>
   <ClCompile Include="a.cpp;b.cpp"/>
</ItemGroup>

    Дополнительные сведения о поддержке подстановочных знаков в проектах и возможных обходных решениях см .vcxproj . в файлах и подстановочных знаках.

  • В настоящее время система проектов Visual Studio C++ не поддерживает макросы в путях элементов проекта. Например, эта форма не поддерживается:

    <ItemGroup>
   <ClCompile Include="$(IntDir)\generated.cpp"/>
</ItemGroup>

    "Не поддерживается" означает, что макросы не гарантированы для всех операций в интегрированной среде разработки. Макросы, которые не изменяют их значение в разных конфигурациях, должны работать, но могут не сохраняться, если элемент перемещается в другой фильтр или проект. Макросы, изменяющие их значение для разных конфигураций, вызывают проблемы. Интегрированная среда разработки не ожидает, что пути к элементу проекта будут отличаться для разных конфигураций проекта.

  • Чтобы добавить, удалить или изменить свойства проекта правильно при их редактировании в диалоговом окне "Свойства проекта", файл должен содержать отдельные группы для каждой конфигурации проекта. Условия должны находиться в следующей форме:

    Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"

  • Каждое свойство должно быть указано в группе с правильной меткой, как указано в файле правила свойства. Дополнительные сведения см. в разделе XML-файлы правил для страниц свойств.

.vcxproj Элементы файла

Содержимое файла можно проверить с помощью любого текстового .vcxproj или XML-редактора. Просмотреть можно и в Visual Studio, щелкнув проект в обозревателе решений, выбрав Выгрузить проект и затем Изменить Foo.vcxproj.

Первое, на что нужно обратить внимание, — это определенный порядок следования элементов верхнего уровня. Например:

  • Большинство групп свойств и групп определений элементов расположено после импорта для Microsoft.Cpp.Default.props.

  • Все целевые объекты импортируются в конце файла.

  • Существует несколько групп свойств, каждая из которых имеет уникальную метку, и все они расположены в определенном порядке.

Порядок элементов в файле проекта жизненно важен, так как MSBuild основан на последовательной модели оценки. Если файл проекта, включая все импортированные .props и .targets файлы, состоит из нескольких определений свойства, последнее определение переопределяет предыдущие. В следующем примере значение "xyz" будет задано во время компиляции, так как подсистема MSBUild встречается последней во время его оценки.

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

В следующем фрагменте кода показан минимальный .vcxproj файл. Любой .vcxproj файл, созданный Visual Studio, будет содержать эти элементы 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

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

Project является корневым узлом. Он задает используемую версию MSBuild, а также целевой объект по умолчанию для выполнения при передаче этого файла в MSBuild.exe.

Элемент ProjectConfigurations ItemGroup

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations содержит описание конфигурации проекта. В качестве примера можно привести Debug|Win32, Release|Win32, Debug|ARM и т. д. Многие параметры проекта относятся к конкретной конфигурации. Например, вы, вероятно, хотите задать свойства оптимизации для сборки выпуска, но не отладочной сборки.

Группа ProjectConfigurations элементов не используется во время сборки. Интегрированная среда разработки Visual Studio требует, чтобы она загружала проект. Эту группу элементов можно переместить в .props файл и импортировать в .vcxproj файл. Однако в этом случае, если необходимо добавить или удалить конфигурации, необходимо вручную изменить .props файл. Вы не можете использовать интегрированную среду разработки.

Элементы ProjectConfiguration

В следующем фрагменте кода показана конфигурация проекта. В этом примере "Отладка|x64" — это имя конфигурации. Имя конфигурации проекта должно быть в формате $(Configuration)|$(Platform). Узел ProjectConfiguration может иметь два свойства: Configuration и Platform. Эти свойства автоматически задаются со значениями, указанными здесь, когда конфигурация активна.

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

Интегрированная среда разработки ожидает найти конфигурацию проекта для любого сочетания и Platform значений, используемых Configuration во всех ProjectConfiguration элементах. Часто это означает, что проект может иметь бессмысленные конфигурации проекта для выполнения этого требования. Например, если проект имеет следующие конфигурации:

  • Debug|Win32;

  • Retail|Win32;

  • Special 32-bit Optimization|Win32;

то он должен содержать и следующие конфигурации, хотя конфигурация Special 32-bit Optimization не имеет смысла для x64:

  • Отладка|x64

  • Retail|x64;

  • Special 32-bit Optimization|x64.

Вы можете отключить команды сборки и развертывания для любой конфигурации в диспетчере конфигурации решения.

Элемент Globals PropertyGroup

<PropertyGroup Label="Globals" />

Globals содержит такие параметры уровня проекта, как ProjectGuid, RootNamespaceили ApplicationType ApplicationTypeRevision. Последние два часто определяют целевую ОС. Проект может использовать только одну ОС, так как в настоящее время ссылки и элементы проекта не могут иметь условий. Эти свойства обычно не переопределяются в другом месте в файле проекта. Эта группа не зависит от конфигурации, и обычно в файле проекта существует только одна 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'") и представлена несколькими копиями — по одной на конфигурации. Эта группа свойств содержит свойства, заданные для конкретной конфигурации. Свойства конфигурации включают 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 (напрямую или через импорт) определяет значения по умолчанию для многих свойств, относящихся к инструменту. Примеры включают свойства оптимизации и уровня предупреждений компилятора, свойство TypeLibraryName средства MIDL и т. д. Он также импортирует различные таблицы системных свойств, на основе которых свойства конфигурации определены в группе свойств непосредственно перед ним.

Элемент ExtensionSettings ImportGroup

<ImportGroup Label="ExtensionSettings" />

Группа ExtensionSettings содержит операции импорта для страниц свойств, входящих в настройки сборки. Настройка сборки определяется до трех файлов: .targets файла, .props файла и .xml файла. Эта группа импорта содержит импорт для .props файла.

Элемент PropertySheets ImportGroup

<ImportGroup Label="PropertySheets" />

Группа PropertySheets содержит операции импорта для страниц свойств. Эти импорты — это листы свойств, которые вы добавляете через представление Диспетчера свойств в Visual Studio. Порядок, в котором указаны эти операции импорта, имеет значение и отражен в диспетчере свойств. Обычно файл проекта содержит несколько экземпляров этого типа группы импорта, по одному для каждой конфигурации проекта.

Элемент UserMacros PropertyGroup

<PropertyGroup Label="UserMacros" />

UserMacros содержит свойства, создаваемые в качестве переменных, которые используются для настройки процесса сборки. Например, можно определить пользовательский макрос для задания настраиваемого пути выходных данных как $(CustomOutputPath) и использовать его для определения других переменных. Эта группа свойств содержит такие свойства. В Visual Studio эта группа не заполняется в файле проекта, так как Visual C++ не поддерживает макросы пользователей для конфигураций. Пользовательские макросы поддерживаются на страницах свойств.

Элементы PropertyGroup для отдельных конфигураций

<PropertyGroup />

Существует несколько экземпляров этой группы свойств, по одному на конфигурацию для всех конфигураций проекта. Каждая группа свойств должна иметь одно прикрепленное условие конфигурации. Если отсутствуют какие-либо конфигурации, диалоговое окно Свойства проекта будет работать неправильно. В отличие от групп свойств, перечисленных ранее, этот не имеет метки. Она содержит параметры на уровне конфигурации проекта. Эти параметры применяются ко всем файлам, входящим в указанную группу элементов. Здесь происходит инициализация метаданных для определения элемента настройки сборки.

Эта группа свойств должна появиться после <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> и не должна существовать другая группа свойств без метки перед ней (в противном случае редактирование свойств проекта не будет работать правильно).

Элементы ItemDefinitionGroup для отдельных конфигураций

<ItemDefinitionGroup />

Содержит определения элемента. Эти определения должны соответствовать тем же правилам условий, что и элементы конфигурации без меток PropertyGroup .

Элементы ItemGroup

<ItemGroup />

ItemGroup элементы содержат элементы (исходные файлы и т. д.) в проекте. Условия не поддерживаются для элементов Project (т. е. типов элементов, которые рассматриваются как элементы проекта по определениям правил).

Метаданные должны иметь условия конфигурации для каждой конфигурации, даже если они одинаковы. Например:

<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 зависит от файла проекта, в котором описано ранее упорядочение. Например, при определении значения свойства на страницах свойств интегрированная среда разработки обычно помещает определение свойства в группу свойств с пустой меткой. Это упорядочение гарантирует, что значения по умолчанию, приведенные в листах системных свойств, переопределяются пользовательскими значениями. Аналогичным образом целевые файлы импортируются в конце, так как они используют свойства, определенные ранее, и так как они обычно не определяют сами свойства. Аналогичным образом листы свойств пользователя импортируются после листов системных свойств (включенных Microsoft.Cpp.props). Этот порядок гарантирует, что пользователь может переопределить все значения по умолчанию, вводимые таблицами системных свойств.

.vcxproj Если файл не соответствует этому макету, результаты сборки могут не быть ожидаемыми. Например, если вы ошибочно импортируете лист системного свойства после листов свойств, определенных пользователем, параметры пользователя переопределяются таблицами системных свойств.

Даже время разработки интегрированной среды разработки зависит от определенной степени от правильного упорядочения элементов. Например, если у файла .vcxproj нет PropertySheets группы импорта, интегрированная среда разработки может не определить, где разместить новый лист свойств, созданный пользователем в Диспетчере свойств. Это может привести к переопределению листа пользователя системным листом. Хотя эвристика, используемая IDE, может допускать незначительные несоответствия в .vcxproj макете файла, настоятельно рекомендуется не отклоняться от структуры, показанной ранее в этой статье.

Использование меток элемента интегрированной средой разработки

В интегрированной среде разработки при установке свойства UseOfAtl на странице общего свойства он записывается в группу свойств Configuration в файле проекта. Свойство TargetName на той же странице свойств записывается в группу свойств без меток для каждой конфигурации. Visual Studio ищет в XML-файле страницы свойств сведения о том, куда нужно записать каждое свойство. На странице общего свойства предполагается, что у вас есть английская версия Visual Studio 2019 выпуск Enterprise, это файл%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. XML-файл правил страницы свойств определяет статические данные о правиле и всех его свойствах. В эти данные входит предпочтительное положение свойства правила в конечном файле (файл, куда будет записано его значение). Предпочтительное положение задается атрибутом 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 по умолчанию VCTargets используется %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargetsпуть.

См. также

Настройка компилятора C++ и свойства сборки в Visual Studio
XML-файлы страницы свойств
Файлы .vcxproj и подстановочные знаки