Asignaciones de proveedor de Microsoft CMakePresets.json y CMakeUserPresets.json

CMake admite dos archivos, CMakePresets.json y CMakeUserPresets.json, 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 se pueden usar para controlar CMake en Visual Studio, 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, mientras que CMakeUserPresets.json está diseñado para que los desarrolladores guarden sus propias compilaciones locales. El esquema de ambos archivos es idéntico.

CMakePresets.json y CMakeUserPresets.json admiten asignaciones de proveedores para almacenar información específica del proveedor. Microsoft mantiene dos asignaciones de proveedores con opciones específicas de Visual Studio y Visual Studio Code. En este caso, documentamos dos asignaciones de proveedor de Microsoft y macros de proveedor de Microsoft. Para obtener más información sobre el resto del esquema, consulte la documentación oficial de CMake. Incluye información sobre los valores preestablecidos de configuración, compilación y prueba.

Para obtener más información sobre cómo usar CMakePresets.json en Visual Studio, consulte Configuración y compilación con valores preestablecidos de CMake en Visual Studio.

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 en VS Code.

Asignación de proveedor de configuración de Visual Studio

Se permite una asignación de proveedor con el URI de proveedor microsoft.com/VisualStudioSettings/CMake/<version> por valor preestablecido de configuración. Contiene opciones específicas de la integración de CMake en Visual Studio y Visual Studio Code. Todas las opciones de la asignación de proveedor se aplican a Visual Studio. Las opciones que se aplican a Visual Studio y a Visual Studio Code están marcadas explícitamente.

Todas las opciones de la asignación de proveedor de configuración de Visual Studio son opcionales y se heredan de los valores preestablecidos de configuración que especifica la clave inherits. En el archivo solo se escriben las opciones que se han modificado. Tanto CMakePresets.json como CMakeUserPresets.json admiten la asignación de proveedor de configuración de Visual Studio.

Las opciones de la asignación de proveedor de configuración de Visual Studio no afectan a la construcción de la línea de comandos de CMake o CTest. De este modo se puede usar el mismo archivo CMakePresets.json para controlar CMake con Visual Studio, con Visual Studio Code y desde la línea de comandos. Las excepciones son las opciones cacheRoot y cmakeGenerateCommand. Estas opciones son específicas del escenario de abrir la caché existente en Visual Studio y no se pueden reproducir desde la línea de comandos.

Configuración	Descripción
hostOS	Matriz de sistemas operativos (SO) admitidos. Los valores aceptados son Windows, Linux y macOS. El valor de hostOS lo usan Visual Studio y Visual Studio Code para ocultar los valores preestablecidos de configuración que no se aplican al sistema operativo del sistema de destino y proporcionar una mejor experiencia de usuario. Si no se especifica hostOS, Visual Studio y Visual Studio Code mostrarán siempre todos los valores preestablecidos de configuración disponibles para seleccionar. Este campo también puede ser una cadena, que es equivalente a una matriz que contiene una cadena. Esta opción es compatible con Visual Studio y Visual Studio Code.
intelliSenseMode	Especifica el modo que se usa para calcular la información de IntelliSense en Visual Studio con el formato <target>-<toolset>-<arch>. Valores aceptados: android-clang-arm android-clang-arm64 android-clang-x6 android-clang-x86 ios-clang-ar ios-clang-arm64 ios-clang-x6 ios-clang-x86 linux-gcc-arm linux-gcc-x64 linux-gcc-x86 windows-clang-arm windows-clang-arm64 windows-clang-x64 windows-clang-x86 windows-msvc-arm windows-msvc-arm64 windows-msvc-x64 windows-msvc-x86 Si no se especifica intelliSenseMode, Visual Studio usa el modo de IntelliSense que coincida con los compiladores especificados y la arquitectura de destino. Se suele usar intelliSenseMode a fin de proporcionar IntelliSense mejorado para la compilación cruzada. En Visual Studio 2019, debe especificar explícitamente un modo clang de IntelliSense al compilar con clang o clang-cl.
intelliSenseOptions	Asignación de opciones de configuración adicionales de IntelliSense. useCompilerDefaults: Unbool que especifica si se usarán las rutas de acceso de inclusión y las definiciones predeterminadas del compilador para IntelliSense. Solo debe ser false si los compiladores que se usan no admiten argumentos de estilo gcc. Tiene como valor predeterminado true. additionalCompilerArgs: matriz de opciones adicionales para controlar IntelliSense en Visual Studio. Esta opción admite la expansión de macros.
enableMicrosoftCodeAnalysis	Valor bool que habilita el análisis de código de Microsoft en Visual Studio al compilar con cl o clang-cl. Tiene como valor predeterminado false.
codeAnalysisRuleset	Especifica el conjunto de reglas que se usará al ejecutar el análisis de código de Microsoft en Visual Studio. Puede usar una ruta de acceso a un archivo de conjunto de reglas, o bien el nombre de un archivo de conjunto de reglas instalado con Visual Studio. Esta opción admite la expansión de macros.
disableExternalAnalysis	Valor bool especifica si el análisis de código debe ejecutarse en encabezados externos en Visual Studio.
codeAnalysisExternalRuleset	Especifica el conjunto de reglas que se usará al ejecutar el análisis de código de Microsoft en un encabezado externo en Visual Studio. Puede usar una ruta de acceso a un archivo de conjunto de reglas, o bien el nombre de un archivo de conjunto de reglas instalado con Visual Studio. Esta opción admite la expansión de macros.
enableClangTidyCodeAnalysis	Valor booleano que habilita el análisis de código de clang-tidy en Visual Studio al compilar con clang-cl. Tiene como valor predeterminado false.
clangTidyChecks	Lista separada por comas de advertencias que se pasan a clang-tidy al ejecutar el análisis de código de clang-tidy en Visual Studio. Se permiten caracteres comodín. El prefijo - quitará las comprobaciones.
cacheRoot	Especifica la ruta de acceso a una caché de CMake. Este directorio debe contener un archivo CMakeCache.txt existente. Esta clave solo es compatible con el escenario de abrir la caché existente en Visual Studio. Esta opción admite la expansión de macros.
cmakeGenerateCommand	Herramienta de línea de comandos (especificada como un programa de línea de comandos y argumentos, por ejemplo, gencache.bat debug) para generar la caché de CMake. Este comando se ejecuta en el shell y utiliza el entorno especificado del valor preestablecido cuando se invoca la configuración de CMake. Esta clave solo es compatible con el escenario de abrir la caché existente en Visual Studio. Esta opción admite la expansión de macros.

Asignación de proveedor de configuración remota de Visual Studio

Se permite una asignación de proveedor con el URI de proveedor microsoft.com/VisualStudioRemoteSettings/CMake/<version> por valor preestablecido de configuración. Contiene opciones específicas de desarrollo remoto en Visual Studio. El desarrollo remoto significa que se invoca CMake en una conexión SSH remota o WSL. Ninguna de las opciones de la asignación de proveedor de configuración remota de Visual Studio se aplica a Visual Studio Code.

Todas las opciones de la asignación de proveedor de configuración remota de Visual Studio son opcionales y se heredan de los valores preestablecidos de configuración que especifica la clave inherits. En el archivo solo se escriben las opciones que se han modificado. Tanto CMakePresets.json como CMakeUserPresets.json admiten la asignación de proveedor de configuración remota de Visual Studio.

Las opciones de la asignación de proveedor de configuración de Visual Studio no afectan a la construcción de la línea de comandos de CMake o CTest. De este modo se puede usar el mismo archivo CMakePresets.json para controlar CMake con Visual Studio, con Visual Studio Code y desde la línea de comandos.

Muchas de las opciones de la asignación de proveedor de configuración remota de Visual Studio se omiten cuando se establece WSL1 como destino. Esto se debe a que el conjunto de herramientas de WSL1 ejecuta todos los comandos localmente y se basa en unidades de Windows montadas en la carpeta /mnt para acceder a archivos de origen locales desde WSL1. No se requiere ninguna copia del archivo de origen. Las opciones que se omiten cuando se establece WSL1 como destino están marcadas explícitamente.

Configuración	Descripción
sourceDir	Ruta de acceso al directorio del sistema remoto donde se copiará el proyecto. Tiene como valor predeterminado $env{HOME}/.vs/$ms{projectDirName}. Esta opción admite la expansión de macros. En escenarios de copia remota, la macro ${sourceDir} se evalúa como el directorio de origen del proyecto en el sistema remoto, y no el directorio de origen del proyecto en el equipo Windows. Los escenarios de copia remota incluyen establecer una conexión SSH remota como destino. En estos casos, el directorio de origen del proyecto en el sistema remoto viene determinado por el valor de sourceDir en la asignación de proveedor de configuración remota de Visual Studio. Esta opción se omite cuando se establece WSL1 como destino.
copySources	Si el valor es true, Visual Studio copiará los orígenes de Windows en el sistema remoto. Establézcalo en false si administra usted mismo la sincronización de archivos. Tiene como valor predeterminado true. Esta opción se omite cuando se establece WSL1 como destino.
copySourcesOptions	Objeto de las opciones relacionadas con la copia de origen de Windows en el sistema remoto. Este objeto se omite cuando se establece WSL1 como destino. copySourcesOptions.exclusionList: lista de rutas de acceso que se excluirán al copiar archivos de origen en el sistema remoto. Una ruta de acceso puede ser el nombre de un archivo o directorio, o bien una ruta de acceso relativa a la raíz de la copia. Tiene como valor predeterminado [ ".vs", ".git", "out" ]. Esta opción admite la expansión de macros. copySourcesOptions.method: método usado para copiar archivos de origen en el sistema remoto. Los valores aceptados son: rsync y sftp. Tiene como valor predeterminado rsync. copySourcesOptions.concurrentCopies: número de copias simultáneas que se usan durante la sincronización de los orígenes con el sistema remoto. Tiene como valor predeterminado 5. copySourcesOptions.outputVerbosity: nivel de detalle de las operaciones de copia de origen en el sistema remoto. Los niveles aceptados son Normal, Verbose y Diagnostic. Tiene como valor predeterminado Normal.
rsyncCommandArgs	Lista de argumentos de la línea de comandos que se pasan a rsync. Tiene como valor predeterminado [ "-t", "--delete", "--delete-excluded" ]. Esta opción admite la expansión de macros y se omite cuando se establece WSL1 como destino.
copyBuildOutput	Especifica si debe volver a copiarse la salida de compilación del sistema remoto en Windows. Tiene como valor predeterminado false. Esta opción se omite cuando se establece WSL1 como destino.
copyOptimizations	Objeto de las opciones relacionadas con las optimizaciones de la copia de origen. Estas opciones se omiten cuando se establece WSL1 como destino. copyOptimizations.maxSmallChange: número máximo de archivos que se van a copiar mediante sftp en lugar de rsync. El valor predeterminado es 10. copyOptimizations.useOptimizations: especifica las optimizaciones de copia en uso. Los valores aceptados son que no haya optimizaciones de copia (None), que haya solo optimizaciones de rsync (RsyncOnly) o que haya optimizaciones de rsync y sftp (RsyncAndSftp). Tiene como valor predeterminado RsyncAndSftp. copyOptimizations.rsyncSingleDirectoryCommandArgs: lista de argumentos de la línea de comandos que se pasan a rsync al copiar el contenido de un único directorio en el sistema remoto. Tiene como valor predeterminado [ "-t", "-d" ]. Esta opción admite la expansión de macros.
copyAdditionalIncludeDirectoriesList	Matriz de rutas de acceso a los directorios de encabezado remotos que se van a copiar localmente para IntelliSense. Esta opción admite la expansión de macros.
copyExcludeDirectoriesList	Lista de rutas de acceso a los directorios de encabezado remotos que no se van a copiar localmente para IntelliSense. Esta opción admite la expansión de macros.
forceWSL1Toolset	Si el valor es true, Visual Studio usa siempre el conjunto de herramientas de WSL1 cuando se establece WSL como destino desde Visual Studio. El conjunto de herramientas de WSL1 ejecuta todos los comandos localmente y se basa en unidades de Windows montadas en la carpeta /mnt para acceder a archivos de origen locales desde WSL. Estas opciones pueden ser más lentas con WSL2. Tiene como valor predeterminado false. En la versión 16.10 de Visual Studio 2019 siempre se usará el conjunto de herramientas de WSL1. Esta opción será pertinente una vez que esté disponible la compatibilidad nativa con WSL2.

Eventos remotos previos y posteriores a la compilación

Con la adopción de CMakePresets.json, las opciones de remotePrebuildEvent y remotePostbuildEvent han quedado en desuso.

Codifique eventos previos a la compilación, previos a la vinculación y posteriores a la compilación en CMakeLists.txt mediante add_custom_command. Esto garantiza el mismo comportamiento al compilar con Visual Studio y desde la línea de comandos.

Si necesita un comportamiento específico de Visual Studio, puede agregar una tarea remota personalizada en tasks.vs.json. Para empezar, haga clic con el botón derecho en el archivo CMakeLists.txt raíz en la vista de carpetas del Explorador de soluciones y seleccione Configurar tareas. Después, puede agregar una nueva tarea remota al archivo tasks.vs.json.

La siguiente tarea remota crea un directorio denominado "test" en el sistema Linux remoto:

{
      "taskLabel": "mkdir",
      "appliesTo": "CMakeLists.txt",
      "type": "remote",
      "command": "mkdir test",
      "remoteMachineName": "localhost"
  }

Haga clic con el botón derecho en cualquier archivo CMakeLists.txt y seleccione la opción mkdir para ejecutar esta tarea.

El valor de remoteMachineName debe coincidir con el nombre de host de una conexión del Administrador de conexiones.

Macros de proveedor de Microsoft

Las dos asignaciones de proveedor de Microsoft, Visual Studio Settings y Visual Studio Remote Settings, admiten todas las macros que define CMake. Nuestras asignaciones de proveedor admiten todas las macros que define CMake. Para obtener más información, consulte Expansión de macros de cmake-presets. Todas las variables de entorno y macros se expanden antes de pasarse a CMake.

Visual Studio admite macros de proveedor con el prefijo ms. Las macros de proveedor de Microsoft solo se pueden usar en asignaciones de proveedor de Microsoft. CMake no puede usar valores preestablecidos que tengan macros de proveedor fuera de una asignación de proveedor.

Macro	Descripción
$ms{projectDirName}	Se evalúa como el nombre de la carpeta abierta en Visual Studio. Esta macro se usa para establecer el valor predeterminado de sourceDir en escenarios de copia remota. Esta macro no es compatible con Visual Studio Code. Use ${sourceDirName} en su lugar.

Variables de entorno

Macro	Descripción
$env{<variable-name>} $penv{<variable-name>}	Haga referencia a variables de entorno mediante esta sintaxis compatible con CMake. Para obtener más información, consulte Expansión de macros de cmake-presets.

Macros en desuso

Con la adopción de CMakePresets.json, algunas macros que eran compatibles con CMakeSettings.json han quedado en desuso.

Use las macros compatibles con CMake para construir las rutas de acceso de archivo. Cuando se usan las macros, esto garantizará que el mismo archivo CMakePresets.json funcione dentro de Visual Studio y desde la línea de comandos.

Macro en desuso	Recomendación
${projectFile}	${sourceDir}/CMakeLists.txt
${thisFile}	${sourceDir}/CMakePresets.json

Sintaxis de shell aceptada

Use la sintaxis $env{HOME} para hacer referencia a $HOME al construir rutas de acceso de Linux en las asignaciones de proveedor de Microsoft.