Configuración y compilación con valores preestablecidos de CMake en Visual Studio

CMake admite dos archivos que permiten a los usuarios especificar opciones comunes de configuración, compilación y prueba y compartirlas con otros usuarios: CMakePresets.json y CMakeUserPresets.json. Use estos archivos para controlar CMake en Visual Studio y en Visual Studio Code, en una canalización de integración continua (CI) y desde la línea de comandos.

CMakePresets.json está pensado para guardar compilaciones para todo el proyecto. CMakeUserPresets.json está diseñado para que los desarrolladores guarden sus propias compilaciones locales. Ambos archivos se admiten en Visual Studio 2019, versión 16.10 o posterior.

Este artículo contiene información sobre la integración de CMakePresets.json en Visual Studio. Aquí hay algunos vínculos útiles:

• Para obtener más información sobre el formato de CMakePresets.json, consulte la documentación oficial de CMake.
• Para obtener más información sobre las asignaciones de proveedor de Microsoft y la expansión de macros, consulte Asignaciones de proveedor de Microsoft CMakePresets.json y CMakeUserPresets.json.
• Para obtener más información sobre cómo usar CMakePresets.json en Visual Studio Code, consulte Configuración y compilación con valores preestablecidos de CMake.

Recomendamos CMakePresets.json como alternativa a CMakeSettings.json. Visual Studio nunca lee de CMakePresets.json y CMakeSettings.json al mismo tiempo. Para habilitar o deshabilitar la integración de CMakePresets.json en Visual Studio, consulte Habilitación de la integración de CMakePresets.json en Visual Studio 2019.

Versiones de CMake y CMakePresets.json compatibles

Las versiones de esquema y CMakeUserPresets.json admitidas CMakePresets.json dependen de la versión de Visual Studio:

• Visual Studio 2019, versión 16.10 y posteriores, admiten versiones de esquema 2 y 3.
• La versión preliminar 17.4 de Visual Studio 2022 agrega compatibilidad con la versión 4 del esquema.
• La versión preliminar 17.5 de Visual Studio 2022 agrega compatibilidad con la versión 5 del esquema.

Para actualizar la versión, cambie el campo "version" en el objeto raíz. Para obtener un ejemplo y más información, consulte Formato de CMakePresets.json.

Se requiere CMake, versión 3.20 o una posterior, al invocar CMake con CMakePresets.json desde la línea de comandos. Aun así, Visual Studio lee y evalúa CMakePresets.json y CMakeUserPresets.json por sí mismo, y no invoca CMake directamente con la opción --preset. Por lo tanto, CMake versión 3.20 o posteriores no es estrictamente necesaria al compilar con CMakePresets.json en Visual Studio.

Se recomienda usar al menos CMake, versión 3.14 o una posterior.

Habilitación de la integración de CMakePresets.json en Visual Studio

La integración de CMakePresets.json no está habilitada de forma predeterminada en Visual Studio. Puede habilitarlo en Herramientas>Opciones>CMake>General:

Esta pantalla se alcanza desde el menú de Visual Studio 2022: Herramientas > Opciones > CMake > General. La opción está en la sección Configurar archivo de CMake.

Importante

Cierre y vuelva a abrir la carpeta en Visual Studio para activar la integración.

En algunas versiones anteriores de Visual Studio, en Herramientas>Opciones>CMake>General solo hay una única opción para habilitar la integración de CMakePresets.json:

En la tabla siguiente se indica cuándo se usa CMakePresets.json en lugar de CMakeSettings.json para controlar la configuración de CMake y compilar en Visual Studio 2022 y Visual Studio 2019, versión 16.10 y posteriores. Si no hay ningún archivo de configuración, se usan los valores preestablecidos de configuración predeterminados.

En la tabla, Herramientas>Opciones habilitadas significa que Use CMakePresets.json to drive CMake configure, build, and test (Usar CMakePresets.json para controlar la configuración, compilación y prueba de CMake) está seleccionado en Herramientas>Opciones>CMake>General.

Archivos de configuración	Herramientas > Opciones deshabilitadas	Herramientas > Opciones habilitadas
No hay presente ningún archivo de configuración	CMakeSettings.json	CMakePresets.json
Está presente CMakeSettings.json	CMakeSettings.json	CMakePresets.json
Está presente CMakePresets.json	CMakePresets.json	CMakePresets.json
Ambos archivos de configuración están presentes	CMakePresets.json	CMakePresets.json

Modificación de la configuración automática y las notificaciones de caché

De forma predeterminada, Visual Studio invoca automáticamente configure cada vez que el sistema de destino activo o los valores preestablecidos de configuración cambian. Para modificar este comportamiento, seleccione No ejecutar nunca el paso de configuración automáticamente en Herramientas>Opciones>CMake>General. También puede deshabilitar todas las notificaciones de caché de CMake (barras doradas). Para ello, anule la selección de Mostrar notificaciones de la memoria caché de CMake.

Valores preestablecidos de configuración predeterminados

Si no existe ningún archivo CMakePresets.json o CMakeUserPresets.json, o si CMakePresets.json o CMakeUserPresets.json no son válidos, Visual Studio recurre a los siguientes valores preestablecidos de configuración predeterminados:

Ejemplo de Windows

{
  "name": "windows-default",
  "displayName": "Windows x64 Debug",
  "description": "Sets Ninja generator, compilers, x64 architecture, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "architecture": {
    "value": "x64",
    "strategy": "external"
  },
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Windows" ]
    }
  }
},

Ejemplo de Linux

{
  "name": "linux-default",
  "displayName": "Linux Debug",
  "description": "Sets Ninja generator, compilers, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Linux" ]
    },
    "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": {
      "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}"
   }
  }
}

Si intenta abrir o modificar un archivo CMakePresets.json que no existe, Visual Studio crea automáticamente un archivo CMakePresets.json con el valor predeterminado Valores preestablecidos de configuración en la raíz del proyecto.

Configuración y compilación

En la barra de herramientas de Visual Studio, hay listas desplegables para los sistemas de destino, Configurar valores preestablecidos y Compilar valores preestablecidos cuando CMakePresets.json la integración está habilitada:

Selección de un sistema de destino

La lista desplegable de la izquierda indica el sistema de destino activo. Se trata del sistema en el que se invocará CMake para configurar y compilar el proyecto. Esta lista desplegable incluye la máquina local, todas las conexiones SSH del Administrador de conexiones por nombre de host y todas las instalaciones de Subsistema de Windows para Linux (WSL) que encuentra Visual Studio:

La lista desplegable contiene varias entradas, como máquina local, una dirección IP 192.168.0.5, WSL: ubuntu2004, WSL: debian y Administrar Conectar ions.

En el ejemplo anterior:

• 192.168.0.5 es un sistema Linux remoto que se agregó al Administrador de conexiones.
• ubuntu2004 y debian son instalaciones de WSL.

Seleccione Administrar conexiones para abrir el Administrador de conexiones.

Selección de un valor preestablecido de configuración

La lista desplegable del centro indica el valor preestablecido de configuración activo. Se trata del valor configurePreset que se usa cuando se invoca CMake para generar el sistema de compilación del proyecto. Esta lista desplegable incluye la unión de valores preestablecidos de configuración no ocultos que están definidos en CMakePresets.json y CMakeUserPresets.json.

Visual Studio usa el valor de hostOS en la asignación de proveedor de configuración de Visual Studio de Microsoft para ocultar los valores preestablecidos de configuración que no se aplican al sistema de destino activo. Para más información, consulte la entrada de hostOS en la tabla de la sección Asignación de proveedor de configuración de Visual Studio.

Seleccione Administrar configuraciones para abrir el archivo CMakePresets.json ubicado en la raíz del proyecto. Si CMakePresets.json no existe, se creará.

Selección de un valor preestablecido de compilación

La lista desplegable de la derecha indica el valor preestablecido de compilación activo. Se trata del valor buildPreset que se usa cuando se invoca CMake para compilar el proyecto. Esta lista desplegable incluye la unión de valores preestablecidos de compilación no ocultos que están definidos en CMakePresets.json y CMakeUserPresets.json.

Todos los valores preestablecidos de compilación son necesarios para especificar un valor configurePreset asociado. Visual Studio oculta los valores preestablecidos de compilación que no se aplican al valor preestablecido de configuración activo. Para obtener más información, vea la lista de valores preestablecidos de compilación.

Si no hay ningún valor preestablecido de compilación asociado al valor preestablecido de configuración activo, Visual Studio muestra el valor preestablecido de compilación predeterminado. El valor preestablecido de compilación predeterminado es equivalente a pasar cmake --build sin ningún otro argumento desde la línea de comandos.

Configurar

Visual Studio intenta automáticamente configurar el proyecto cuando detecta que la caché de CMake no está actualizada. Para invocar manualmente la configuración, seleccione Proyecto>Configurar <nombre de proyecto> en el menú principal. Esto es lo mismo que ejecutar cmake --preset <configurePreset> desde la línea de comandos, donde <configurePreset> es el nombre del valor preestablecido de configuración activo.

Para deshabilitar la generación automática de caché, consulte Configuración automática y notificaciones de caché.

Build

Para compilar todo el proyecto, seleccione Compilar>Compilar todo en el menú principal. Esto es lo mismo que ejecutar cmake --build --preset <buildPreset> desde la línea de comandos, donde <buildPreset> es el nombre del valor preestablecido de compilación activo.

Para compilar un único destino, cambie a la Vista de destinos de CMake en el Explorador de soluciones. Después, haga clic con el botón derecho en cualquier destino y seleccione Compilar en el menú contextual.

Nota:

Visual Studio 2019 no admite la opción buildPresets.targets para compilar un subconjunto de destinos especificados en CMakePresets.json.

Ejecución de CTest

CMakePresets.json admite dos opciones de menú en Visual Studio 2019:

• Prueba>Ejecutar CTests para <nombre de proyecto> invoca CTest y ejecuta todas las pruebas asociadas con los valores preestablecidos de configuración y compilación activos, sin que se pasen otros argumentos a CTest.
• Prueba>Ejecutar valor preestablecido de prueba para <configurePreset> se expande para mostrar todos los valores preestablecidos de prueba asociados al valor preestablecido de configuración activo. Seleccionar un único valor preestablecido de prueba es lo mismo que ejecutar ctest --preset <testPreset> desde la línea de comandos, donde <testPreset> es el nombre del valor preestablecido de prueba seleccionado. Esta opción no está disponible si no se define ningún valor preestablecido de prueba para el valor preestablecido de configuración activo.

En Visual Studio 2019, el Explorador de pruebas no está integrado con CMakePresets.json.

Adición de nuevos valores preestablecidos

En Visual Studio 2019, todos los comandos y plantillas preestablecidas modifican CMakePresets.json. Puede agregar nuevos valores preestablecidos de nivel de usuario si edita directamente CMakeUserPresets.json.

Use una barra diagonal (/) para las rutas de acceso de CMakePresets.json y CMakeUserPresets.json.

Adición de nuevos valores preestablecidos de configuración

Para agregar un nuevo valor preestablecido de configuración a CMakePresets.json, vaya al Explorador de soluciones, haga clic con el botón derecho en CMakePresets.json en la Vista de carpetas y seleccione Agregar configuración en el menú contextual. Aparece el cuadro de diálogo para seleccionar una plantilla de valor preestablecido de configuración:

Seleccione la plantilla Windows x64 Debug (Depuración en Windows x64) para realizar la configuración en sistemas Windows. Seleccione la plantilla Linux Debug (Depuración en Linux) para realizar la configuración en WSL y sistemas Linux remotos. Para más información sobre cómo editar CMakePresets.json, consulte Edición de valores preestablecidos.

La plantilla seleccionada se agrega a CMakePresets.json, si existe. En caso contrario, la plantilla se copia en un nuevo archivo CMakePresets.json.

Adición de nuevos valores preestablecidos de compilación y prueba

Visual Studio 2019 no ofrece plantillas para nuevos valores preestablecidos de compilación y prueba. Puede agregar valores preestablecidos de compilación y prueba si se edita CMakePresets.json directamente. Para obtener más información, vea la lista de valores preestablecidos de compilación, la lista de valores preestablecidos de prueba o un archivo CMakePresets.json de ejemplo.

Edición de valores preestablecidos

La documentación oficial de CMake es el mejor recurso para editar valores preestablecidos de configuración, compilación y prueba. La siguiente información es un subconjunto de la documentación de CMake que resulta de especial importancia para los desarrolladores de Visual Studio.

Selección de los compiladores

Puede establecer los compiladores de C y C++ se pueden establecer mediante cacheVariables.CMAKE_C_COMPILER y cacheVariables.CMAKE_CXX_COMPILER en un valor preestablecido de configuración. Equivale a pasar -D CMAKE_C_COMPILER=<value> y -D CMAKE_CXX_COMPILER=<value> a CMake desde la línea de comandos. Para obtener más información, vea CMAKE_<LANG>_COMPILER.

Use los ejemplos siguientes para compilar con cl.exe y clang-cl.exe desde Visual Studio. El componente Herramientas de Clang en C++ para Windows debe estar instalado para compilar con clang-cl.

Compilación con cl.exe:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "cl",
  "CMAKE_CXX_COMPILER": "cl"
},

Compilación con clang:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "clang-cl",
  "CMAKE_CXX_COMPILER": "clang-cl"
},

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Si usa Visual Studio 16 2019 o Visual Studio 17 2022 como generador, puede usar Configurar valores predeterminados de toolset para especificar el conjunto de herramientas de ClangCL:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
},

"toolset": "ClangCL",

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Para obtener más información sobre los generadores que admiten la especificación toolset, consulte CMAKE_GENERATOR_TOOLSET en la documentación de CMake.

Importante

En Visual Studio 2019, debe especificar explícitamente un modo Clang de IntelliSense al compilar con clang o clang-cl.

Para reproducir estas compilaciones fuera de Visual Studio, vea Ejecución de CMake desde la línea de comandos o una canalización de integración continua (CI).

Para compilar en Linux o sin el conjunto de herramientas de Visual C++, especifique el nombre de un compilador en la instancia de PATH o una variable de entorno que se evalúe como la ruta de acceso completa de un compilador. Para que el archivo pueda seguir compartiéndose, no se recomienda usar rutas de acceso completas. Un valor preestablecido que compila con GCC versión 8 podría tener este aspecto:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "gcc-8",
  "CMAKE_CXX_COMPILER": "g++-8"
},

También puede establecer compiladores con un archivo de cadena de herramientas de CMake. Se pueden establecer archivos de cadena de herramientas con cacheVariables.CMAKE_TOOLCHAIN_FILE, lo que equivale a pasar -D CMAKE_TOOLCHAIN_FILE=<value> a CMake desde la línea de comandos. Los archivos de cadena de herramientas de CMake suelen usarse para la compilación cruzada. Para más información sobre la creación de archivos de cadena de herramientas de CMake, consulte Cadenas de herramientas de CMake.

Selección del generador

Las plantillas de valores preestablecidos de configuración de Windows y Linux especifican Ninja como generador predeterminado. Otros generadores comunes son los generadores de Visual Studio en archivos Make de Windows y Unix en Linux y macOS. Puede especificar un nuevo generador con la opción generator en un valor preestablecido de configuración. Equivale a pasar -G a CMake desde la línea de comandos.

Establezca architecture.strategy y toolset.strategy en set al compilar con un generador de Visual Studio. Para más información, consulte Generadores de CMake.

Selección del tipo de configuración

Puede establecer el tipo de configuración (Debug o Release) para los generadores de configuración única mediante cacheVariables.CMAKE_BUILD_TYPE. Equivale a pasar -D CMAKE_BUILD_TYPE=<value> a CMake desde la línea de comandos. Para obtener más información, vea CMAKE_BUILD_TYPE.

Seleccione la arquitectura de destino y de host al compilar con el conjunto de herramientas de Visual C++.

Puede establecer la arquitectura de destino (x64, Win32, ARM64 o ARM) mediante architecture.value. Equivale a pasar -A a CMake desde la línea de comandos. Para más información, consulte Selección de la plataforma.

Nota:

Actualmente, los generadores de Visual Studio esperan la sintaxis Win32 y los generadores de línea de comandos (como Ninja) esperan la sintaxis x86 al compilar para x86.

Puede establecer la arquitectura de host (x64 o x86) y el conjunto de herramientas mediante toolset.value. Equivale a pasar -T a CMake desde la línea de comandos. Para más información, consulte Selección del conjunto de herramientas.

Los valores architecture.strategy y toolset.strategy indican a CMake cómo controlar los campos de arquitectura y de conjunto de herramientas. set significa que CMake establece el valor correspondiente, mientras que external significa que CMake no establece el valor correspondiente.

Recomendamos que use set con generadores de IDE, como el generador de Visual Studio. Use external con generadores de línea de comandos, como Ninja. Estos valores permiten a proveedores como Visual Studio proporcionar el entorno necesario antes de invocar CMake. Para más información sobre los campos de arquitectura y de conjunto de herramientas, consulte la lista de valores preestablecidos de configuración.

Si no quiere tener un entorno como origen, puede establecer architecture.strategy en external y architecture.value en unspecified. Es posible que le sea útil no tener un entorno como origen por cualquiera de estos motivos:

• Usa un conjunto de herramientas que no sea MSVC.
• Usa una cadena de herramientas personalizada, como en escenarios incrustados.
• No necesita un entorno específico para la compilación.

Para obtener una lista completa de los generadores de IDE que admiten el campo de arquitectura, consulte CMAKE_GENERATOR_PLATFORM. Para obtener una lista completa de los generadores de IDE que admiten el campo de conjunto de herramientas, consulte CMAKE_GENERATOR_TOOLSET.

Use los ejemplos siguientes para establecer como destino ARM64 con el generador de Ninja o Win32 (x86) con el generador de Visual Studio 16 2019:

"generator": "Ninja",
"architecture": {
    "strategy": "external",
    "value": "arm64"
},

"generator": "Visual Studio 16 2019",
"architecture": {
    "strategy": "set",
     "value": "Win32"
},

Establecimiento de variables de entorno y referencia a estas

Puede establecer variables de entorno mediante la asignación de entorno. Las variables de entorno se heredan a través del campo inherits, pero se pueden invalidar si así lo desea.

El entorno de un valor preestablecido es la unión de su propio entorno y el entorno de todos sus elementos primarios. Si varios valores preestablecidos inherits proporcionan valores en conflicto para la misma variable, se da preferencia al valor preestablecido que aparezca primero en la lista inherits. Puede anular una variable heredada de otro valor preestablecido si la establece en null.

Las variables de entorno establecidas en un valor preestablecido de configuración también se pasan automáticamente a los valores preestablecidos de compilación y prueba asociados, a menos que inheritConfigureEnvironment esté establecido en false. Para obtener más información, vea la lista de valores preestablecidos de configuración.

Puede hacer referencia a variables de entorno mediante la sintaxis $env{<variable-name>} y $penv{<variable-name>}. Para más información, consulte Expansión de macros.

Configuración de IntelliSense para un compilador cruzado

De forma predeterminada, Visual Studio usa el modo de IntelliSense que coincida con los compiladores especificados y la arquitectura de destino. Si va a realizar una compilación cruzada, es posible que deba especificar manualmente el modo de IntelliSense correcto con la opción intelliSenseMode en la asignación de proveedor de configuración de Visual Studio. Para más información, consulte la entrada de intelliSenseMode en la tabla de la sección Asignación de proveedor de configuración de Visual Studio.

Configuración y compilación en un sistema remoto o en el Subsistema de Windows para Linux

Gracias a la compatibilidad con CMakePresets.json en Visual Studio, puede configurar y compilar fácilmente el proyecto en Windows, WSL y sistemas remotos. Los pasos para configurar y compilar el proyecto en Windows, un sistema remoto o WSL son los mismos. Aun así, hay algunos comportamientos específicos del desarrollo remoto.

Comportamiento de ${sourceDir} en escenarios de copia remota

En escenarios locales (incluido WSL1), ${sourceDir} se evalúa como la ruta de acceso al directorio de origen del proyecto que está abierto en Visual Studio. En escenarios de copia remota, ${sourceDir} se evalúa como la ruta de acceso al directorio de origen del proyecto en el sistema de destino, y no el directorio de origen del proyecto en el equipo local.

El valor de sourceDir en el mapa del proveedor de configuración remota de Visual Studio determina el directorio de origen del proyecto en el sistema de destino (el valor predeterminado es $env{HOME}/.vs/$ms{projectDirName}). Para más información, consulte la entrada de sourceDir en la tabla de la sección Asignación de proveedor de configuración de Visual Studio.

Carpeta local para la salida remota

Los escenarios de copia remota requieren un directorio local para copiar algunos archivos remotos, como los archivos de compilación o de respuesta de la API de archivos de CMake si copyBuildOutput está establecido en true en la asignación del proveedor de configuración remota de Visual Studio. Estos archivos se copian automáticamente en <local-source-directory>/out/<remote-connection-ID>/build/${presetName}.

Invocación del mismo valor preestablecido de configuración en Windows y WSL1

Verá un error si intenta usar el mismo valor preestablecido de configuración en Windows y WSL1. Windows y WSL1 usan el sistema de archivos de Windows, por lo que CMake intentará usar el mismo directorio de salida (binaryDir) para el árbol de compilación de Windows y WSL1.

Si quiere usar el mismo valor preestablecido de configuración con Windows y el conjunto de herramientas de WSL1, cree un segundo valor preestablecido de configuración que herede del valor preestablecido original y especifique un nuevo valor binaryDir. En el ejemplo siguiente, se puede usar windows-preset en Windows y base-preset en WSL1:

{
  "name": "windows-preset",
  "inherits": "base-preset",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": "Windows"
    }
  }
}

Nota:

En Visual Studio 2019, solo se admite el conjunto de herramientas de WSL1. Verá este comportamiento cada vez que invoque configure en Windows y WSL.

Habilitación de la integración de vcpkg

Vcpkg ayuda a administrar bibliotecas de C y C++ en Windows, Linux y macOS. Se debe pasar un archivo de cadena de herramientas de vcpkg (vcpkg.cmake) a CMake para habilitar la integración de vcpkg. Para más información, consulte la documentación de vcpkg.

Visual Studio ya no pasa automáticamente el archivo de cadena de herramientas de vcpkg a CMake cuando se habilita la integración de CMakePresets.json. Este cambio elimina el comportamiento específico de Visual Studio y garantiza que usted pueda reproducir la compilación desde la línea de comandos.

En su lugar, establezca la ruta de acceso en vcpkg.cmake con la variable de entorno VCPKG_ROOT en CMakePresets.json:

"cacheVariables": {
   "CMAKE_TOOLCHAIN_FILE": {
      "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
       "type": "FILEPATH"
    }
 },

VCPKG_ROOT debe establecerse en la raíz de la instalación de vcpkg. Para más información, consulte Variables de entorno de vcpkg.

Si ya usa un archivo de cadena de herramientas de CMake y desea habilitar la integración de vcpkg, consulte Uso de varios archivos de cadena de herramientas. Siga estas instrucciones para usar un archivo de cadena de herramientas externo con un proyecto mediante vcpkg.

Sustitución de variables en launch.vs.json y tasks.vs.json

CMakePresets.json admite la sustitución de variables en launch.vs.json y tasks.vs.json. A continuación, se indican algunas consideraciones:

• Las variables de entorno establecidas en el valor preestablecido de configuración activo pasan automáticamente a las configuraciones de launch.vs.json y tasks.vs.json. Puede anular variables de entorno individuales en launch.vs.json y tasks.vs.json si las establece en null. En el ejemplo siguiente se establece la variable DEBUG_LOGGING_LEVEL en null en launch.vs.json: "env": { "DEBUG_LOGGING_LEVEL": null }.

• Los valores de clave definidos en el valor preestablecido de configuración activo están disponibles para su consumo en launch.vs.json y tasks.vs.json con la sintaxis ${cmake.<KEY-NAME>}. Por ejemplo, use ${cmake.binaryDir} para hacer referencia al directorio de salida del valor preestablecido de configuración activo.

• Las variables de entorno individuales establecidas en la asignación de entorno del valor preestablecido de configuración activo están disponibles para su consumo en launch.vs.json y tasks.vs.json mediante la sintaxis de ${env.<VARIABLE-NAME>}.

Actualice los archivos launch.vs.json y task.vs.json para que hagan referencia a la sintaxis de CMakePresets.json, en lugar de a la sintaxis de CMakeSettings.json. Las macros que hacen referencia a la sintaxis antigua de CMakeSettings.json cuando CMakePresets.json es el archivo de configuración activo dejarán de usarse en una versión futura. Por ejemplo, haga referencia al directorio de salida del valor preestablecido de configuración activo con ${cmake.binaryDir} en lugar de ${cmake.buildRoot}, porque CMakePresets.json usa la sintaxis de binaryDir.

Solución de problemas

Si las cosas no funcionan según lo previsto, puede seguir una serie de pasos para solucionar los problemas.

Si CMakePresets.json o CMakeUserPresets.json no son válidos, Visual Studio recurrirá a su comportamiento predeterminado y solo mostrará los valores preestablecidos de configuración predeterminados. IntelliSense de Visual Studio puede ayudarle a detectar muchos de estos errores de JSON, pero no sabrá si se está haciendo referencia a un valor preestablecido con inherits o configurePreset con un nombre incorrecto.

Para comprobar si los archivos preestablecidos son válidos, ejecute cmake --list-presets desde la línea de comandos en la raíz del directorio del proyecto. (Se requiere CMake 3.20 o versiones posteriores). Si alguno de los archivos no es válido, verá el siguiente error:

CMake Error: Could not read presets from
C:/Users/<user>/source/repos/<project-name>: JSON parse error

Otros pasos para solucionar problemas incluyen:

• Eliminar la memoria caché y volver a configurar el proyecto (CMake: Eliminar caché y Proyecto>Configurar <nombre del proyecto>).
• Cerrar y volver a abrir la carpeta en Visual Studio (Cerrar>Cerrar carpeta).
• Eliminar la carpeta .vs en la raíz del proyecto.

Si ha identificado un problema, la mejor manera de notificarlo consiste en seleccionar el botón Enviar comentarios de la esquina superior derecha de Visual Studio.

Administración del registro para las conexiones remotas

Puede habilitar el registro de las conexiones remotas si tiene problemas para conectar o copiar archivos en un sistema remoto. Para más información, consulte Registro de las conexiones remotas.

Habilitación de AddressSanitizer para Windows y Linux

Visual Studio admite AddressSanitizer (ASan), un detector de errores de memoria en tiempo de ejecución de C y C++ para el desarrollo de Windows y Linux. La opción addressSanitizerEnabled de CMakeSettings.json habilita AddressSanitizer. CMakePresets.json no es compatible con este comportamiento.

Para habilitar y deshabilitar AddressSanitizer, establezca usted mismo las marcas necesarias del compilador y del enlazador. Al establecerlas, se elimina el comportamiento específico de Visual Studio y se garantiza que el mismo archivo CMakePresets.json pueda reproducir la compilación desde la línea de comandos.

Puede agregar el ejemplo siguiente a CMakeLists.txt para habilitar o deshabilitar AddressSanitizer para un destino:

option(ASAN_ENABLED "Build this target with AddressSanitizer" ON)

if(ASAN_ENABLED)
  if(MSVC)
    target_compile_options(<target> PUBLIC /fsanitize=address)
  else()
    target_compile_options(<target> PUBLIC -fsanitize=address <additional-options>)
    target_link_options(<target> PUBLIC -fsanitize=address)
  endif()
endif()

En la parte <additional-options> se enumeran otras marcas de compilación, como "-fno-omit-frame-pointer". Para obtener más información sobre AddressSanitizer para Linux, consulte Uso de AddressSanitizer. Para obtener más información sobre cómo usar AddressSanitizer con MSVC, consulte Uso de AddressSanitizer desde un símbolo del sistema para desarrolladores.

Pase marcas en tiempo de ejecución a AddressSanitizer mediante el campo ASAN_OPTIONS de launch.vs.json. ASAN_OPTIONS tiene el valor predeterminado de detect_leaks=0 cuando no se especifica ninguna otra opción de entorno de ejecución porque no se admite LeakSanitizer en Visual Studio.

Ejecución de CMake desde la línea de comandos o una canalización de integración continua

Puede usar los mismos archivos CMakePresets.json y CMakeUserPresets.json para invocar CMake en Visual Studio y desde la línea de comandos. La documentación de CMake y CTest es el mejor recurso para invocar CMake y CTest con --preset. Se requiere CMake versión 3.20 o posteriores.

Obtención del entorno al compilar con generadores de línea de comandos en Windows

El usuario debe configurar el entorno antes de que se invoque CMake al compilar con un generador de línea de comandos. Si va a compilar con Ninja y el conjunto de herramientas de Visual C++ en Windows, establezca el entorno antes de llamar a CMake para generar el sistema de compilación. Para ello, llame a vcvarsall.bat con el argumento architecture. El argumento architecture especifica la arquitectura de host y de destino que se van a usar. Para obtener más información, consulte Sintaxis de vcvarsall. Si realiza la compilación en Linux o en Windows con un generador de Visual Studio, no es necesario llevar a cabo este paso.

Es el mismo paso que Visual Studio realiza automáticamente cuando el IDE invoca CMake. Visual Studio analiza el valor preestablecido de configuración activo para el host y la arquitectura de destino que se especifican mediante toolset y architecture. Visual Studio, a continuación, obtiene el entorno especificado de vcvarsall.bat. Al compilar desde la línea de comandos de Windows con Ninja, deberá llevar a cabo este paso usted mismo.

vcvarsall.bat se instala con las herramientas de compilación para Visual Studio. De forma predeterminada, vcvarsall.bat se instala en C:\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\VC\Auxiliary\Build. Puede agregar vcvarsall.bat a PATH si usa el flujo de trabajo de la línea de comandos con frecuencia.

Ejemplo de flujo de trabajo de línea de comandos

Puede usar los siguientes comandos para configurar y compilar un proyecto de CMake que use Ninja para establecer como destino ARM64 con herramientas de compilación x64. Se requiere CMake versión 3.20 o posteriores. Ejecute estos comandos desde el directorio donde se encuentra el archivo CMakePresets.json:

/path/to/vcvarsall.bat x64_arm64 
cmake --list-presets=all .
cmake --preset <configurePreset-name>
cmake --build --preset <buildPreset-name> 

Archivo CMakePresets.json de ejemplo

El archivo CMakePresets.json de box2d-lite contiene ejemplos de valores preestablecidos de configuración, compilación y prueba. Para obtener más información sobre este ejemplo, vea la presentación Introducción a CMakePresets.json. Puede ver otro ejemplo en el proyecto DirectXTK, que muestra muchos destinos de compilación en su sección configurePresets.

Pasos siguientes

Más información sobre cómo configurar y depurar proyectos de CMake en Visual Studio:

Proyectos de CMake en Visual Studio
Personalización de la configuración de compilación de CMake
Configuración de sesiones de depuración de CMake
Referencia de configuración predefinida de CMake