.vcxproj a .props struktura souborů

  • Článek

MSBuild je výchozí systém projektů v sadě Visual Studio. Když v sadě Visual C++ zvolíte Soubor>nový projekt, vytváříte projekt MSBuild, jehož nastavení jsou uložena v souboru projektu XML, který má příponu ..vcxproj Soubor projektu může také importovat .props soubory a .targets soubory, kde je možné nastavení uložit.

Pokud máte v úmyslu udržovat vlastnosti projektu v integrovaném vývojovém prostředí (IDE), doporučujeme vytvářet a upravovat pouze projekty .vcxproj v integrovaném vývojovém prostředí (IDE) a vyhnout se ručním úpravám souborů. Ve většině případů nemusíte soubor projektu upravovat ručně. Ruční úpravy můžou přerušit připojení projektu potřebná k úpravě nastavení projektu na stránkách vlastností sady Visual Studio a způsobit chyby sestavení, které se obtížně ladí a opravují. Další informace o používání stránek vlastností naleznete v tématu Nastavení kompilátoru C++ a vlastností sestavení v sadě Visual Studio.

Ve velkém se správa mnoha jednotlivých projektů v integrovaném vývojovém prostředí stává zdlouhavou a náchylnou k chybám. Je obtížné zachovat konzistenci nebo vynutit standardizaci napříč desítkami nebo stovkami projektů. V těchto případech je vhodné upravit soubory projektu tak, aby používaly .props přizpůsobené soubory nebo .targets soubory pro běžné vlastnosti v mnoha projektech. Tyto soubory můžete použít také v případech, kdy potřebujete vlastní nastavení, která nejsou v integrovaném vývojovém prostředí možná. Praktická místa pro vložení vlastních nastavení jsou soubory Directory.Build.props Directory.Build.targets , které se automaticky importují ve všech projektech založených na nástroji MSBuild.

V některých případech nemusí být vlastní .props soubory nebo .targets soubory dostatečné pro potřeby řízení projektů. Možná budete muset soubory projektu nebo seznamy vlastností upravit .vcxproj ručně. Ruční úpravy vyžadují dobré znalosti nástroje MSBuild a musí dodržovat pokyny v tomto článku. Aby integrované vývojové prostředí (IDE) načítá a aktualizovalo .vcxproj soubory automaticky, mají tyto soubory několik omezení, která neplatí pro jiné soubory projektu NÁSTROJE MSBuild. Chyby můžou způsobit chybové ukončení nebo chování integrovaného vývojového prostředí (IDE) neočekávaným způsobem.

Pro scénáře ruční úpravy obsahuje tento článek základní informace o struktuře .vcxproj a souvisejících souborech.

Důležitá poznámka

Pokud se rozhodnete soubor upravit .vcxproj ručně, mějte na paměti tyto skutečnosti:

  • Struktura souboru musí odpovídat předepsané formě, která je popsána v tomto článku.

  • Systém projektů Visual Studio C++ v současné době nepodporuje zástupné cardy ani seznamy přímo v položkách projektu. Například tyto formuláře nejsou podporované:

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

    Další informace o podpoře zástupných znaků v projektech a možných alternativních řešeních najdete v tématu .vcxproj Soubory a zástupné dokumentace.

  • Systém projektů Visual Studio C++ v současné době nepodporuje makra v cestách položek projektu. Tento formulář například není podporovaný:

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

    Nepodporováno znamená, že makra nemusí fungovat pro všechny operace v integrovaném vývojovém prostředí( IDE). Makra, která nemění jejich hodnotu v různých konfiguracích, by měla fungovat, ale nemusí být zachována, pokud je položka přesunuta do jiného filtru nebo projektu. Makra, která mění jejich hodnotu pro různé konfigurace, způsobí problémy. Integrované vývojové prostředí (IDE) neočekává, že se cesty položek projektu budou pro různé konfigurace projektu lišit.

  • Chcete-li přidat, odebrat nebo upravit vlastnosti projektu správně při úpravách v dialogovém okně Vlastnosti projektu, musí soubor obsahovat samostatné skupiny pro každou konfiguraci projektu. Podmínky musí být v této podobě:

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

  • Každá vlastnost musí být zadána ve skupině se správným popiskem, jak je uvedeno v souboru pravidla vlastnosti. Další informace naleznete v tématu Soubory pravidel stránky vlastností xml.

.vcxproj elementy souboru

Obsah souboru můžete zkontrolovat pomocí libovolného textového .vcxproj editoru nebo editoru XML. V sadě Visual Studio ho můžete zobrazit tak, že v Průzkumník řešení kliknete pravým tlačítkem na projekt, zvolíte Možnost Uvolnit projekt a pak zvolíte Upravit Foo.vcxproj.

První věc, kterou si můžete všimnout, je, že prvky nejvyšší úrovně se zobrazují v určitém pořadí. Příklad:

  • Většina skupin vlastností a skupin definic položek probíhá po importu pro Microsoft.Cpp.Default.props.

  • Všechny cíle se naimportují na konci souboru.

  • Existuje více skupin vlastností, z nichž každý má jedinečný popisek a dochází k nim v určitém pořadí.

Pořadí prvků v souboru projektu je zásadně důležité, protože NÁSTROJ MSBuild je založen na sekvenčním modelu vyhodnocení. Pokud se soubor projektu, včetně všech importovaných .props a .targets souborů, skládá z více definic vlastnosti, poslední definice přepíše předchozí. V následujícím příkladu bude hodnota "xyz" nastavena během kompilace, protože modul MSBUild narazí na to, že je poslední během vyhodnocení.

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

Následující fragment kódu ukazuje minimální .vcxproj soubor. Všechny .vcxproj soubory vygenerované sadou Visual Studio budou obsahovat tyto elementy MSBuild nejvyšší úrovně. A v tomto pořadí se zobrazí, i když můžou obsahovat více kopií každého takového prvku nejvyšší úrovně. Všechny Label atributy jsou libovolné značky, které sada Visual Studio používá pouze jako symboly pro úpravy. Nemají žádnou jinou funkci.

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

Následující části popisují účel každého z těchto prvků a důvod jejich řazení tímto způsobem:

Project – element

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

Project je kořenový uzel. Určuje verzi nástroje MSBuild, která se má použít, a také výchozí cíl, který se má spustit, když se tento soubor předá MSBuild.exe.

ProjectConfigurations ItemGroup – element

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations obsahuje popis konfigurace projektu. Příklady jsou Ladění |Win32, Release|Win32, Ladění |ARM a tak dále. Mnoho nastavení projektu je specifické pro danou konfiguraci. Budete například pravděpodobně chtít nastavit vlastnosti optimalizace pro sestavení vydané verze, ale ne ladicí sestavení.

Skupina ProjectConfigurations položek se v době sestavení nepoužívá. Integrované vývojové prostředí sady Visual Studio vyžaduje, aby se projekt načetl. Tuto skupinu položek lze přesunout do .props souboru a importovat do souboru .vcxproj . Pokud ale potřebujete přidat nebo odebrat konfigurace, musíte soubor upravit ručně .props . Integrované vývojové prostředí (IDE) ale nemůžete použít.

Elementy ProjectConfiguration

Následující fragment kódu ukazuje konfiguraci projektu. V tomto příkladu je název konfigurace Debug|x64. Název konfigurace projektu musí být ve formátu $(Configuration)|$(Platform). Uzel ProjectConfiguration může mít dvě vlastnosti: Configuration a Platform. Tyto vlastnosti se nastaví automaticky s hodnotami zadanými zde, pokud je konfigurace aktivní.

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

Integrované vývojové prostředí očekává, že najde konfiguraci projektu pro libovolnou kombinaci Configuration a Platform hodnoty použité ve všech ProjectConfiguration položkách. Často to znamená, že projekt může mít pro splnění tohoto požadavku nesmyslné konfigurace projektu. Pokud má například projekt tyto konfigurace:

  • Ladění |Win32

  • Maloobchod |Win32

  • Speciální 32bitová optimalizace|Win32

pak musí mít také tyto konfigurace, i když "Speciální 32bitová optimalizace" je pro x64 bez významu:

  • Ladění|x64

  • Maloobchod|x64

  • Speciální 32bitová optimalizace|x64

Příkazy sestavení a nasazení můžete zakázat pro libovolnou konfiguraci v nástroji Solution Configuration Manager.

Element Globals PropertyGroup

<PropertyGroup Label="Globals" />

Globals obsahuje nastavení na úrovni projektu, například ProjectGuid, RootNamespacea ApplicationType nebo ApplicationTypeRevision. Poslední dva často definují cílový operační systém. Projekt může cílit pouze na jeden operační systém, protože v současné době nemůžou mít odkazy a položky projektu podmínky. Tyto vlastnosti obvykle nejsou přepsány jinde v souboru projektu. Tato skupina není závislá na konfiguraci a obvykle v souboru projektu existuje pouze jedna Globals skupina.

Microsoft.Cpp.default.props Import – element

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

Seznam vlastností Microsoft.Cpp.default.props je součástí sady Visual Studio a nedá se upravit. Obsahuje výchozí nastavení projektu. Výchozí hodnoty se můžou lišit v závislosti na typu ApplicationType.

Elementy Configuration PropertyGroup

<PropertyGroup Label="Configuration" />

Skupina Configuration vlastností má připojenou podmínku konfigurace (například Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") a dodává se v několika kopiích, jednu na konfiguraci. Tato skupina vlastností hostuje vlastnosti nastavené pro konkrétní konfiguraci. Vlastnosti konfigurace zahrnují PlatformToolset a také řídí zahrnutí seznamů systémových vlastností do Microsoft.Cpp.props. Pokud například definujete vlastnost , pak seznam systémových vlastností <CharacterSet>Unicode</CharacterSet>microsoft. Cpp.unicodesupport.props bude zahrnuta. Pokud zkontrolujete Microsoft.Cpp.props, zobrazí se řádek: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Microsoft.Cpp.props – element Import

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

Seznam vlastností Microsoft.Cpp.props (přímo nebo prostřednictvím importu) definuje výchozí hodnoty pro mnoho vlastností specifických pro nástroj. Mezi příklady patří vlastnosti optimalizace a úrovně upozornění kompilátoru, vlastnost TypeLibraryName nástroje MIDL atd. Také importuje různé systémové seznamy vlastností na základě toho, které vlastnosti konfigurace jsou definovány ve skupině vlastností bezprostředně před ní.

ExtensionSettings ImportGroup – element

<ImportGroup Label="ExtensionSettings" />

Skupina ExtensionSettings obsahuje importy pro seznamy vlastností, které jsou součástí vlastních nastavení sestavení. Vlastní nastavení sestavení je definováno až třemi soubory: .targets souborem, .props souborem a souborem .xml . Tato skupina importu obsahuje importy souboru .props .

Elementy PropertySheets ImportGroup

<ImportGroup Label="PropertySheets" />

Skupina PropertySheets obsahuje importy pro seznamy vlastností uživatele. Tyto importy jsou seznamy vlastností, které přidáte prostřednictvím zobrazení Správce vlastností v sadě Visual Studio. Pořadí, ve kterém jsou tyto importy uvedeny, je důležité a odráží se ve Správci vlastností. Soubor projektu obvykle obsahuje více instancí tohoto typu skupiny importu, jednu pro každou konfiguraci projektu.

UserMacros PropertyGroup – element

<PropertyGroup Label="UserMacros" />

UserMacros obsahuje vlastnosti, které vytvoříte jako proměnné, které slouží k přizpůsobení procesu sestavení. Můžete například definovat uživatelské makro pro definování vlastní výstupní cesty jako $(CustomOutputPath) a použít ho k definování dalších proměnných. Tato vlastnost seskupuje takové vlastnosti. V sadě Visual Studio není tato skupina naplněna v souboru projektu, protože Visual C++ nepodporuje uživatelská makra pro konfigurace. Uživatelská makra jsou podporována v listech vlastností.

Elementy PropertyGroup pro konfiguraci

<PropertyGroup />

Existuje několik instancí této skupiny vlastností, jedna na konfiguraci pro všechny konfigurace projektu. Každá skupina vlastností musí mít připojenou jednu podmínku konfigurace. Pokud nějaké konfigurace chybí, dialogové okno Vlastnosti projektu nebude fungovat správně. Na rozdíl od skupin vlastností uvedených dříve tento seznam nemá popisek. Tato skupina obsahuje nastavení na úrovni konfigurace projektu. Tato nastavení platí pro všechny soubory, které jsou součástí zadané skupiny položek. Tady se inicializují metadata definice položky vlastního nastavení.

Tato skupina PropertyGroup musí pocházet <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> a před ní nesmí existovat žádná jiná skupina PropertyGroup bez popisku (jinak úpravy vlastností projektu nebudou fungovat správně).

Elementy ItemDefinitionGroup pro konfiguraci

<ItemDefinitionGroup />

Obsahuje definice položek. Tyto definice musí dodržovat stejná pravidla podmínek jako elementy konfigurace bez PropertyGroup popisků.

Elementy ItemGroup

<ItemGroup />

ItemGroup elementy obsahují položky (zdrojové soubory atd.) v projektu. Podmínky nejsou podporovány pro položky projektu (to znamená typy položek, které jsou považovány za položky projektu podle definic pravidel).

Metadata by měla mít pro každou konfiguraci podmínky konfigurace, i když jsou všechny stejné. Příklad:

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

Systém projektů Visual Studio C++ v současné době nepodporuje zástupné cardy v položkách projektu.

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

Systém projektů Visual Studio C++ v současné době nepodporuje makra v položkách projektu.

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

Odkazy jsou zadané ve skupině ItemGroup a mají tato omezení:

  • Odkazy nepodporují podmínky.

  • Metadata odkazů nepodporují podmínky.

Microsoft.Cpp.targets – element Import

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

Definuje (přímo nebo prostřednictvím importů) cíle jazyka C++, jako je sestavení, čištění atd.

ExtensionTargets ImportGroup – element

<ImportGroup Label="ExtensionTargets" />

Tato skupina obsahuje importy pro cílové soubory vlastního nastavení sestavení.

Důsledky nesprávného řazení

Integrované vývojové prostředí sady Visual Studio závisí na souboru projektu, který má pořadí popsané výše. Když například definujete hodnotu vlastnosti na stránkách vlastností, integrované vývojové prostředí obecně umístí definici vlastnosti do skupiny vlastností s prázdným popiskem. Toto řazení zajišťuje, že výchozí hodnoty přenesené do seznamů vlastností systému budou přepsány uživatelsky definovanými hodnotami. Podobně se cílové soubory naimportují na konci, protože spotřebovávají vlastnosti definované dříve, a protože obvykle nedefinují vlastnosti samy. Podobně se seznamy vlastností uživatele importují po listech systémových vlastností (včetně Microsoft.Cpp.props). Toto pořadí zajišťuje, že uživatel může přepsat všechny výchozí hodnoty, které jsou uvedeny v seznamu systémových vlastností.

.vcxproj Pokud soubor nevyhovuje tomuto rozložení, nemusí výsledky sestavení vypadat tak, jak očekáváte. Pokud například omylem importujete seznam systémových vlastností po listech vlastností definovaných uživatelem, přepíše se uživatelské nastavení seznamem systémových vlastností.

I doba návrhu integrovaného vývojového prostředí závisí na určitém rozsahu na správném pořadí prvků. Pokud .vcxproj například soubor nemá skupinu importu PropertySheets , integrované vývojové prostředí (IDE) nemusí být schopné určit, kam umístit nový seznam vlastností, který uživatel vytvořil ve Správci vlastností. Může to vést k přepsání uživatelského listu systémovým listem. I když heuristické použití integrovaného vývojového prostředí může tolerovat menší nekonzistence v .vcxproj rozložení souboru, důrazně doporučujeme, abyste se neodchýlili od struktury uvedené výše v tomto článku.

Jak integrované vývojové prostředí (IDE) používá popisky elementů

Když v integrovaném vývojovém prostředí nastavíte vlastnost UseOfAtl na stránce obecné vlastnosti, zapíše se do skupiny vlastností Konfigurace v souboru projektu. Vlastnost TargetName na stejné stránce vlastností je zapsána do skupiny vlastností bez popisků na konfiguraci. Visual Studio hledá v souboru XML stránky vlastností informace o tom, kde zapisovat jednotlivé vlastnosti. Pro stránku vlastností Obecné za předpokladu, že máte anglickou verzi sady Visual Studio 2019 edice Enterprise, je tento %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xmlsoubor . Soubor pravidla XML stránky vlastností definuje statické informace o pravidle a všech jeho vlastnostech. Jednou z takových informací je upřednostňovaná pozice vlastnosti Rule v cílovém souboru (soubor, kde bude zapsána jeho hodnota). Upřednostňovaná pozice je určena atributem Popisek u elementů souboru projektu.

Rozložení Seznam vlastností

Následující fragment kódu XML je minimální rozložení souboru seznamu vlastností (.props). Podobá se .vcxproj souboru a funkce .props prvků lze odvodit z předchozí diskuze.

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

Pokud chcete vytvořit vlastní seznam vlastností, zkopírujte jeden ze .props souborů ve VCTargets složce a upravte ho pro vaše účely. Pro edici Visual Studio 2019 Enterprise je %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargetsvýchozí VCTargets cesta .

Viz také

Nastavení vlastností kompilátoru a sestavení C++ v sadě Visual Studio
Soubory XML stránky vlastností
.vcxproj soubory a zástupné cardy