Tutorial: Usar MSBuild para crear un proyecto de Visual C++

En este tutorial se muestra cómo usar MSBuild en un símbolo del sistema para compilar un proyecto de Visual Studio C++. Va a aprender a crear un archivo del proyecto .vcxproj basado en XML para una aplicación de consola de Visual C++. Después de compilar el proyecto, aprenderá a personalizar el proceso de compilación.

Importante

No use este enfoque si piensa editar el archivo del proyecto más adelante mediante el IDE de Visual Studio. Si crea un archivo .vcxproj manualmente, es posible que el IDE de Visual Studio no pueda editarlo o cargarlo, sobre todo si el proyecto usa caracteres comodín en los elementos del proyecto. Para obtener más información, vea Estructura de los archivos .vcxproj y .props y Archivos .vcxproj y comodines.

En el tutorial se muestran las tareas siguientes:

• Crear archivos de código fuente de C++ para el proyecto.
• Crear el archivo de proyecto de MSBuild en XML.
• Usar MSBuild para compilar el proyecto.
• Usar MSBuild para personalizar el proyecto.

Requisitos previos

Para realizar este tutorial se necesitan estos requisitos previos:

• Una copia de Visual Studio que tenga instalada la carga de trabajo Desarrollo de escritorio con C++.
• Conocimientos generales sobre el sistema MSBuild.

Nota:

La mayoría de las instrucciones de compilación de bajo nivel se encuentran en los archivos .targets y .props definidos en la carpeta targets predeterminada, almacenada en la propiedad $(VCTargetsPath). Ahí se encuentran archivos como Microsoft.Cpp.Common.props. La ruta de acceso predeterminada de estos archivos está en %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\. El elemento de la ruta de acceso <version> es específico de la versión de Visual Studio. Es v160 en el caso de Visual Studio 2019. Visual Studio 2017 almacenaba estos archivos en %VSINSTALLDIR%Common7\IDE\VC\VCTargets\. Visual Studio 2015 y versiones anteriores los almacenaban en %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\.

Creación de los archivos de origen de C++

En este tutorial, creará un proyecto que tiene un archivo de origen y un archivo de encabezado. El archivo de origen main.cpp contiene la función main de la aplicación de consola. El archivo de encabezado main.h contiene código para incluir el archivo de encabezado <iostream>. Puede crear estos archivos de C++ mediante Visual Studio o un editor de texto, Visual Studio Code.

Para crear archivos de código fuente de C++ para el proyecto

1. Cree una carpeta para el proyecto.

2. Cree un archivo denominado main.cpp y agréguele este código:

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

3. Cree un archivo denominado main.h y agréguele este código:

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

Crear el archivo de proyecto de MSBuild en XML

Un archivo de proyecto de MSBuild es un archivo XML que contiene un elemento raíz de proyecto (<Project>). En el proyecto de ejemplo que ha compilado, el elemento <Project> contiene siete elementos secundarios:

• Tres etiquetas de grupo de elementos (<ItemGroup>) que especifican la configuración del proyecto y la plataforma, el nombre del archivo de código fuente y el nombre del archivo de encabezado.
• Tres etiquetas de importación (<Import>) que especifican la ubicación de la configuración de Microsoft Visual C++.
• Una etiqueta de grupo de propiedades (<PropertyGroup>) que especifica la configuración del proyecto.

Para crear el archivo de proyecto de MSBuild

1. Use un editor de texto para crear un archivo del proyecto con el nombre myproject.vcxproj y luego agregue el elemento raíz <Project> que se muestra aquí. (Use ToolsVersion="14.0" si tiene Visual Studio 2015, ToolsVersion="15.0" si tiene Visual Studio 2017 o ToolsVersion="16.0" si tiene Visual Studio 2019).

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

   Inserte los elementos de los siguientes pasos del procedimiento entre las etiquetas raíz <Project>.

2. Agregue estos dos elementos secundarios <ProjectConfiguration> a un elemento <ItemGroup>. El elemento secundario especifica las configuraciones de depuración y de versión de un sistema operativo 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. Agregue un elemento <Import> que especifica la ruta de acceso de la configuración predeterminada de C++ de este proyecto:

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

4. Agregue un elemento de grupo de propiedades (<PropertyGroup>) que especifica dos propiedades del proyecto, <ConfigurationType> y <PlatformToolset>. (Use v140 como valor <PlatformToolset> si tiene Visual Studio 2015, v141 si tiene Visual Studio 2017 o v142 si tiene Visual Studio 2019).

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

5. Agregue un elemento <Import> que especifica la ruta de acceso de la configuración actual de C++ de este proyecto:

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

6. Agregue un elemento secundario <ClCompile> a un elemento <ItemGroup>. El elemento secundario especifica el nombre del archivo de código fuente de C/C++ que se va a compilar:

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

   Nota:

   <ClCompile> es un destino de compilación y se define en la carpeta targets predeterminada.

7. Agregue un elemento secundario <ClInclude> a un elemento <ItemGroup>. El elemento secundario especifica el nombre del archivo de encabezado para el archivo de código fuente de C/C++:

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

8. Agregue un elemento <Import> que especifica la ruta de acceso del archivo que define el destino de este proyecto:

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

Completar el archivo de proyecto

Este código muestra el archivo del proyecto completo creado en el procedimiento anterior. (Use ToolsVersion="15.0" para Visual Studio 2017 o ToolsVersion="14.0" para 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>

Usar MSBuild para compilar el proyecto

Escriba este comando en el símbolo del sistema para compilar la aplicación de consola:

msbuild myproject.vcxproj /p:configuration=debug

MSBuild crea una carpeta para los archivos de salida y luego compila y vincula el proyecto para generar el programa Myproject.exe. Al finalizar el proceso de compilación, use este comando para ejecutar la aplicación desde la carpeta de depuración:

myproject

La aplicación debe mostrar "¡Hola, de parte de MSBuild!" en la ventana de la consola.

Personalizar el proyecto

MSBuild permite ejecutar destinos de compilación predefinidos, aplicar propiedades definidas por el usuario y usar herramientas, eventos y pasos de compilación personalizados. En esta sección se explican estas tareas:

• Usar MSBuild con destinos de compilación.
• Usar MSBuild con propiedades de compilación.
• Usar MSBuild con las herramientas y el compilador de 64 bits.
• Usar MSBuild con conjuntos de herramientas diferentes.
• Agregar personalizaciones de MSBuild.

Usar MSBuild con destinos de compilación

Un destino de compilación es un conjunto con nombre de comandos predefinidos o definidos por el usuario que se pueden ejecutar durante la compilación. Use la opción de línea de comandos de destino (/t) para especificar un destino de compilación. En el proyecto de ejemplo myproject, el destino clean predefinido elimina todos los archivos de la carpeta de depuración y crea un nuevo archivo de registro.

En el símbolo del sistema, escriba este comando para limpiar myproject:

msbuild myproject.vcxproj /t:clean

Usar MSBuild con propiedades de compilación

La opción de línea de comandos de propiedad (/p) permite reemplazar una propiedad en el archivo de compilación del proyecto. En el proyecto de ejemplo myproject, la configuración de compilación de versión o de depuración se especifica mediante la propiedad Configuration. El sistema operativo que va a usar para ejecutar la aplicación compilada se especifica mediante la propiedad Platform.

En el símbolo del sistema, escriba este comando para crear una compilación de depuración de la aplicación myproject que se ejecute en Windows de 32 bits:

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

Supongamos que el proyecto de ejemplo myproject también define una configuración para Windows de 64 bits y otra configuración para un sistema operativo personalizado denominado myplatform.

En el símbolo del sistema, escriba este comando para crear una compilación de versión que se ejecute en Windows de 64 bits:

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

En el símbolo del sistema, escriba este comando para crear una compilación de versión para myplatform:

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

Usar MSBuild con las herramientas y el compilador de 64 bits

Si ha instalado Visual Studio en Windows de 64 bits, las herramientas cruzadas y nativas x64 de 64 bits se instalan de forma predeterminada. Puede configurar MSBuild para usar las herramientas y el compilador de 64 bits para compilar la aplicación mediante la configuración de la propiedad PreferredToolArchitecture. Esta propiedad no afecta a las propiedades de la plataforma o la configuración del proyecto. De forma predeterminada, se usa la versión de 32 bits de las herramientas. Para especificar la versión de 64 bits del compilador y las herramientas, agregue este elemento de grupo de propiedades al archivo del proyecto Myproject.vcxproj después del elemento <Import /> del archivo Microsoft.Cpp.default.props:

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

En el símbolo del sistema, escriba este comando para usar las herramientas de 64 bits para compilar la aplicación:

msbuild myproject.vcxproj /p:PreferredToolArchitecture=x64

Usar MSBuild con conjuntos de herramientas diferentes

Si tiene instalados conjuntos de herramientas y bibliotecas para otras versiones de Visual C++, MSBuild puede compilar las aplicaciones para la versión de Visual C++ actual o para las demás versiones instaladas. Por ejemplo, si ha instalado Visual Studio 2012, para especificar el conjunto de herramientas de Visual C++ 11.0 para Windows XP, agregue este elemento de grupo de propiedades al archivo del proyecto Myproject.vcxproj después del elemento <Import /> del archivo Microsoft.Cpp.props:

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

Para recompilar el proyecto con el conjunto de herramientas de Visual C++ 11.0 para Windows XP, escriba este comando:

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

Agregar personalizaciones de MSBuild

MSBuild ofrece varias maneras de personalizar el proceso de compilación. En estos artículos se explica cómo agregar pasos de compilación, herramientas y eventos personalizados a un proyecto de MSBuild:

• Procedimiento para agregar un paso de compilación personalizado a proyectos de MSBuild
• Procedimiento para agregar herramientas de compilación personalizadas a proyectos de MSBuild
• Procedimiento para usar eventos de compilación en proyectos de MSBuild

Consulte también

• vcpkg en proyectos de MSBuild
• Tutorial: Instalación y uso de paquetes con MSBuild en Visual Studio