Instruções passo a passo: usando MSBuild para criar um projeto do Visual Studio 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 baseado em .vcxproj XML para um aplicativo de console C++. Depois de criar o projeto, você aprenderá a personalizar o processo de build.

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.

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 o local das configurações do Microsoft 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, ToolsVersion="16.0" se estiver usando o Visual Studio 2019 ou ToolsVersion="17.0" se estiver usando o Visual Studio 2022.)

   <Project DefaultTargets="Build" ToolsVersion="17.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 valor se você estiver usando o Visual Studio 2015, <PlatformToolset> se estiver usando o v141 Visual Studio 2017, v142 se estiver usando o Visual Studio 2019 ou v143 se estiver usando o Visual Studio 2022.)

   <PropertyGroup>
     <ConfigurationType>Application</ConfigurationType>
     <PlatformToolset>v143</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=16.0 for Visual Studio 2019, ToolsVersion="15.0" para o Visual Studio 2017 ou ToolsVersion="14.0" para o Visual Studio 2015.)

<Project DefaultTargets="Build" ToolsVersion="17.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 Compilação

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 Microsoft.Cpp.default.props do arquivo <Import />:

<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 bibliotecas para outras versões do Microsoft C++ (MSVC) instalados, o MSBuild poderá criar aplicativos para a versão atual do MSVC 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 Microsoft.Cpp.props do arquivo <Import />:

<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