Instruções passo a passo: usando MSBuild para criar um projeto do Visual C++

Este passo a passo demonstra como usar o MSBuild em um prompt de comando para criar um projeto do Visual Studio C++. Você aprenderá a criar um arquivo de projeto .vcxproj baseado em XML para um aplicativo de console Visual C++. Depois de criar o projeto, você aprenderá a personalizar o processo de build.

Importante

Não use essa abordagem se você pretende editar o arquivo de projeto posteriormente usando o IDE do Visual Studio. Se você criar um arquivo .vcxproj manualmente, talvez o IDE do Visual Studio não consiga editá-lo nem carregá-lo, especialmente se o projeto usar curingas nos itens de projeto. Para obter mais informações, confira a estrutura de arquivos .vcxproj e .props e caracteres curinga e arquivos .vcxproj.

Esta explicação passo a passo ilustra as seguintes tarefas:

• Criar arquivos de origem C++ para o projeto.
• Criar o arquivo de projeto XML do MSBuild.
• Usar o MSBuild para compilar o projeto.
• Usar o MSBuild para personalizar o projeto.

Pré-requisitos

Você precisa dos seguintes itens para concluir este guia passo a passo:

• Uma cópia do Visual Studio com a carga de trabalho Desenvolvimento para desktop com C++ instalada.
• Uma compreensão geral do sistema MSBuild.

Observação

A maioria das instruções de build de nível inferior está contida nos arquivos .targets e .props definidos na pasta de destinos padrão, armazenada na propriedade $(VCTargetsPath). É nela que você encontrará arquivos como Microsoft.Cpp.Common.props. O caminho padrão para esses arquivos está em %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\. O elemento de caminho <version> é específico para cada versão do Visual Studio. Ele é v160 para o Visual Studio 2019. O Visual Studio 2017 armazenava esses arquivos em %VSINSTALLDIR%Common7\IDE\VC\VCTargets\. O Visual Studio 2015 e versões anteriores os armazenavam em %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\.

Criar os arquivos de origem do C++

Neste passo a passo, você criará um projeto que tem um arquivo de origem e um arquivo de cabeçalho. O arquivo de origem main.cpp contém a função main para o aplicativo de console. O arquivo de cabeçalho main.h contém o código para incluir o arquivo de cabeçalho <iostream>. Crie esses arquivos C++ usando o Visual Studio ou um editor de texto como o Visual Studio Code.

Para criar os arquivos de origem C++ do projeto

1. Crie uma pasta para seu projeto.

2. Crie um arquivo chamado main.cpp e adicione este código ao arquivo:

   // main.cpp : the application source code.
   #include <iostream>
   #include "main.h"
   int main()
   {
      std::cout << "Hello, from MSBuild!\n";
      return 0;
   }
   

3. Crie um arquivo chamado main.h e adicione este código ao arquivo:

   // main.h: the application header code.
   /* Additional source code to include. */
   

Como criar o arquivo de projeto XML do MSBuild

Um arquivo de projeto do MSBuild é um arquivo XML que contém um elemento raiz do projeto (<Project>). No seguinte projeto que você compilará, o elemento <Project> contém sete elementos filho:

• Três marcas de grupo de itens (<ItemGroup>) que especificam a configuração do projeto e a plataforma, o nome do arquivo de origem e o nome do arquivo de cabeçalho.
• Três marcas de importação (<Import>) que especificam a localização das configurações do Microsoft Visual C++.
• Uma tag de grupo de propriedades (<PropertyGroup>) que especifica as configurações do projeto.

Para criar o arquivo de projeto do MSBuild

1. Use um editor de texto para criar um arquivo de projeto chamado myproject.vcxproj e, em seguida, adicione o elemento <Project> raiz mostrado aqui. (Use ToolsVersion="14.0" se você estiver usando o Visual Studio 2015, ToolsVersion="15.0" se estiver usando o Visual Studio 2017 ou ToolsVersion="16.0" se estiver usando o Visual Studio 2019.)

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

   Insira os elementos nas etapas do procedimento a seguir entre as marcas <Project> raiz.

2. Adicione os dois elementos filho <ProjectConfiguration> a seguir a um elemento <ItemGroup>. O elemento filho especifica as configurações de depuração e versão para um sistema operacional Windows de 32 bits:

   <ItemGroup>
     <ProjectConfiguration Include="Debug|Win32">
       <Configuration>Debug</Configuration>
       <Platform>Win32</Platform>
     </ProjectConfiguration>
     <ProjectConfiguration Include="Release|Win32">
       <Configuration>Release</Configuration>
       <Platform>Win32</Platform>
     </ProjectConfiguration>
   </ItemGroup>
   

3. Adicione um elemento <Import> que especifica o caminho das configurações padrão do C++ para este projeto:

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

4. Adicione um elemento de grupo de propriedades (<PropertyGroup>) que especifica duas propriedades do projeto, <ConfigurationType> e <PlatformToolset>. (Use v140 como o valor <PlatformToolset> se você estiver usando o Visual Studio 2015, v141 se estiver usando o Visual Studio 2017 ou v142 se estiver usando o Visual Studio 2019.)

   <PropertyGroup>
     <ConfigurationType>Application</ConfigurationType>
     <PlatformToolset>v142</PlatformToolset>
   </PropertyGroup>
   

5. Adicione um elemento <Import> que especifica o caminho das configurações atuais do C++ para este projeto:

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

6. Adicione um elemento filho <ClCompile> em um elemento <ItemGroup>. O elemento filho especifica o nome do arquivo de origem C/C++ a ser compilado:

   <ItemGroup>
     <ClCompile Include="main.cpp" />
   </ItemGroup>
   

   Observação

   <ClCompile> é um destino de build e é definido na pasta de destinos padrão.

7. Adicione um elemento filho <ClInclude> em um elemento <ItemGroup>. O elemento filho especifica o nome do arquivo de cabeçalho do arquivo de origem C/C++:

   <ItemGroup>
     <ClInclude Include="main.h" />
   </ItemGroup>
   

8. Adicione um elemento <Import> que especifica o caminho do arquivo que define o destino para este projeto:

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

Arquivo de projeto completo

Este código mostra o arquivo de projeto completo criado no procedimento anterior. (Use ToolsVersion="15.0" para o Visual Studio 2017 ou ToolsVersion="14.0" para o Visual Studio 2015.)

<Project DefaultTargets="Build" ToolsVersion="16.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <ProjectConfiguration Include="Debug|Win32">
      <Configuration>Debug</Configuration>
      <Platform>Win32</Platform>
    </ProjectConfiguration>
    <ProjectConfiguration Include="Release|Win32">
      <Configuration>Release</Configuration>
      <Platform>Win32</Platform>
    </ProjectConfiguration>
  </ItemGroup>
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
  <PropertyGroup>
    <ConfigurationType>Application</ConfigurationType>
    <PlatformToolset>v142</PlatformToolset>
  </PropertyGroup>
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
  <ItemGroup>
    <ClCompile Include="main.cpp" />
  </ItemGroup>
  <ItemGroup>
    <ClInclude Include="main.h" />
  </ItemGroup>
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Targets" />
</Project>

Como usar o MSBuild para compilar seu projeto

Insira o seguinte comando no prompt de comando para compilar seu aplicativo de console:

msbuild myproject.vcxproj /p:configuration=debug

O MSBuild cria uma pasta para os arquivos de saída e, em seguida, compila e vincula o projeto para gerar o programa Myproject.exe. Depois que o processo de build for concluído, use o seguinte comando para executar o aplicativo na pasta de depuração:

myproject

O aplicativo deve exibir "Olá, do MSBuild!" na janela do console.

Como personalizar seu projeto

O MSBuild permite que você execute destinos de build predefinidos, aplique propriedades definidas pelo usuário e use ferramentas, etapas de build e eventos personalizados. Esta seção ilustra as seguintes tarefas:

• Usar o MSBuild com destinos de build.
• Usar o MSBuild com propriedades de build.
• Usar o MSBuild com as ferramentas e o compilador de 64 bits.
• Usar o MSBuild com diferentes conjuntos de ferramentas.
• Adicionar personalizações do MSBuild.

Como usar o MSBuild com destinos de build

Um destino de build é um conjunto nomeado de comandos predefinidos ou definidos pelo usuário que podem ser executados durante o build. Use a opção de linha de comando de destino (/t) para especificar um destino de build. Para o projeto de exemplo myproject, o destino clean predefinido exclui todos os arquivos da pasta de depuração e cria um arquivo de log.

No prompt de comando, insira o seguinte comando para limpar myproject:

msbuild myproject.vcxproj /t:clean

Como usar o MSBuild com propriedades de build

A opção de linha de comando de propriedade (/p) permite que você substitua uma propriedade no arquivo de build do projeto. No projeto de exemplo myproject, a configuração de build de versão ou depuração é especificada pela propriedade Configuration. O sistema operacional que você usará para executar o aplicativo compilado é especificado pela propriedade Platform.

No prompt de comando, insira o seguinte comando para criar um build de depuração do aplicativo myproject a ser executado no Windows de 32 bits:

msbuild myproject.vcxproj /p:configuration=debug /p:platform=win32

Suponha que o projeto de exemplo myproject também defina uma configuração para o Windows de 64 bits e outra configuração para um sistema operacional personalizado chamado myplatform.

No prompt de comando, insira o seguinte comando para criar um build de versão que é executado no Windows de 64 bits:

msbuild myproject.vcxproj /p:configuration=release /p:platform=x64

No prompt de comando, insira o seguinte comando para criar um build de versão para myplatform:

msbuild myproject.vcxproj /p:configuration=release /p:platform=myplatform

Como usar o MSBuild com as ferramentas e o compilador de 64 bits

Se você tiver instalado o Visual Studio no Windows de 64 bits, as ferramentas nativas e cruzadas do x64 de 64 bits estarão instaladas por padrão. Configure o MSBuild para usar as ferramentas e o compilador de 64 bits a fim de compilar seu aplicativo definindo a propriedade PreferredToolArchitecture. Essa propriedade não afeta as propriedades de configuração do projeto nem da plataforma. Por padrão, a versão de 32 bits das ferramentas é usada. Para especificar a versão de 64 bits do compilador e das ferramentas, adicione o seguinte elemento de grupo de propriedades ao arquivo de projeto Myproject.vcxproj após o elemento <Import /> do arquivo Microsoft.Cpp.default.props:

<PropertyGroup>
    <PreferredToolArchitecture>x64</PreferredToolArchitecture>
</PropertyGroup>

No prompt de comando, insira o seguinte comando para usar as ferramentas de 64 bits para compilar o aplicativo:

msbuild myproject.vcxproj /p:PreferredToolArchitecture=x64

Como usar o MSBuild com um conjunto de ferramentas diferente

Se você tiver os conjuntos de ferramentas e as bibliotecas de outras versões do Visual C++ instaladas, o MSBuild poderá compilar aplicativos para a versão atual do Visual C++ ou para as outras versões instaladas. Por exemplo, se você tiver instalado o Visual Studio 2012, para especificar o Conjunto de ferramentas do Visual C++ 11.0 para Windows XP, adicione o seguinte elemento de grupo de propriedades ao arquivo de projeto Myproject.vcxproj após o elemento <Import /> do arquivo Microsoft.Cpp.props:

<PropertyGroup>
    <PlatformToolset>v110_xp</PlatformToolset>
</PropertyGroup>

Para recompilar o projeto com o Conjunto de ferramentas do Visual C++ 11.0 para Windows XP, insira o seguinte comando:

msbuild myproject.vcxproj /p:PlatformToolset=v110_xp /t:rebuild

Como adicionar personalizações do MSBuild

O MSBuild fornece várias maneiras de personalizar o processo de build. Os seguintes artigos mostram como adicionar etapas de build, ferramentas e eventos personalizados ao projeto do MSBuild:

• Como adicionar uma etapa de build personalizada a projetos MSBuild
• Como adicionar ferramentas de build personalizadas a projetos MSBuild
• Como usar eventos de build em projetos do MSBuild

Confira também

• vcpkg em projetos do MSBuild
• Tutorial: Instalar e usar pacotes com o MSBuild no Visual Studio