Personalización de la configuración de compilación de CMake

Visual Studio usa un archivo de configuración de CMake para impulsar la generación y la compilación de CMake. CMakePresets.json es admitido con Visual Studio 2019, versión 16.10 o posterior, y es el archivo de configuración de CMake recomendado. CMake admite directamenteCMakePresets.json y se puede usar para impulsar la generación y compilación de CMake desde Visual Studio, desde VS Code, en una canalización de integración continua y desde la línea de comandos en Windows, Linux y Mac. Para obtener más información sobre CMakePresets.json, consulte Configurar y compilar con valores preestablecidos de CMake.

Si mantiene proyectos que usan un archivo CMakeSettings.json para la configuración de compilación de CMake, Visual Studio 2019 y versiones posteriores proporcionan un editor de configuración de CMake. El editor le permite agregar configuraciones de CMake y personalizar su configuración fácilmente. Está pensado para ser una alternativa más sencilla para editar manualmente el archivo CMakeSettings.json. Sin embargo, si prefiere editar directamente el archivo, puede seleccionar el vínculo Editar JSON en la esquina superior derecha del editor.

Para abrir el editor de configuración de CMake, seleccione el menú desplegable Configuración de la barra de herramientas y seleccione Administrar configuraciones.

Ahora puede ver el Editor de configuración con las configuraciones instaladas en la parte izquierda.

De forma predeterminada, Visual Studio proporciona una configuración x64-Debug. Puede agregar más configuraciones eligiendo el signo más de color verde. Los valores que se ven en el editor pueden variar en función de la configuración seleccionada.

Las opciones que elige en el editor se escriben en un archivo denominado CMakeSettings.json. Este archivo proporciona argumentos de la línea de comandos y variables de entorno que se pasan a CMake al compilar los proyectos. Visual Studio nunca modifica CMakeLists.txt de forma automática; mediante CMakeSettings.json, puede personalizar la compilación a través de Visual Studio mientras deja intactos los archivos de proyecto de CMake para que otros miembros del equipo puedan consumirlos con las herramientas que usan.

Configuración general de CMake

Las opciones siguientes están disponibles en el encabezado General:

Nombre de la configuración

Se corresponde al valor name. Este nombre aparece en la lista desplegable de configuración de C++. Puede usar la macro ${name} para crear otros valores de propiedad, como rutas de acceso.

Tipo de configuración

Se corresponde al valor configurationType. Define el tipo de configuración de compilación para el generador seleccionado. Los valores admitidos actualmente son Debug, MinSizeRel, Release y RelWithDebInfo. Se asigna a CMAKE_BUILD_TYPE.

Conjunto de herramientas

Se corresponde al valor inheritedEnvironments. Define el entorno del compilador que se usa para compilar la configuración seleccionada. Los valores admitidos dependen del tipo de configuración. Para crear un entorno personalizado, haga clic en el vínculo Editar JSON en la esquina superior derecha del editor de configuración y edite directamente el archivo CMakeSettings.json.

Archivo de cadena de herramientas de CMake

Ruta de acceso al archivo de cadena de herramientas de CMake. Esta ruta de acceso se pasa a CMake como "-DCMAKE_TOOLCHAIN_FILE = <filepath>. Los archivos de cadena de herramientas especifican las ubicaciones de los compiladores y las utilidades de cadena de herramientas, así como otra información relacionada con el compilador y la plataforma de destino. De forma predeterminada, Visual Studio usa el archivo de cadena de herramientas de vcpkg si no se especifica esta configuración.

Raíz de la compilación

Se corresponde a buildRoot. Se asigna a CMAKE_BINARY_DIR y se especifica dónde se creará la caché de CMake. Si la carpeta especificada no existe, se creará.

Los argumentos de comandos

Las opciones siguientes están disponibles en el encabezado Argumentos de comandos:

Argumentos de comandos de CMake

Se corresponde a cmakeCommandArgs. Especifica más opciones de línea de comandos que se pasan a CMake.

Argumentos de comandos de compilación

Se corresponde a buildCommandArgs. Especifica más modificadores que se pasarán al sistema de compilación subyacente. Por ejemplo, pasar -v cuando se usa el generador Ninja obliga a Ninja a generar líneas de comandos.

Argumentos de comandos de CTest

Se corresponde a ctestCommandArgs. Especifica más opciones de línea de comandos que se pasarán a CTest al ejecutar las pruebas.

Configuración general para compilaciones remotas

Para las configuraciones como Linux en las que se usan compilaciones remotas, también están disponibles las opciones siguientes:

Argumentos del comando rsync

Opciones adicionales de la línea de comandos pasadas a rsync, una herramienta de copia de archivos rápida y versátil.

Caché y variables de CMake

Estas opciones permiten establecer variables de CMake y guardarlas en CMakeSettings.json. Se pasan a CMake en tiempo de compilación y reemplazan los valores que contiene el archivo CMakeLists.txt. Puede usar esta sección de la misma manera que usaría CMakeGUI para ver una lista de todas las variables de CMake disponibles para editar. Elija el botón Guardar y generar caché para ver una lista de todas las variables de CMake disponibles para editar, incluidas las variables avanzadas (según CMakeGUI). Puede filtrar la lista por nombre de variable.

Se corresponde a variables. Contiene un par nombre-valor de variables de CMake que se pasan como -D name=value a CMake. Si las instrucciones de compilación del proyecto de CMake especifican la adición de las variables directamente al archivo de caché de CMake, en su lugar se recomienda agregarlas aquí.

Configuración avanzada

Generador de CMake

Se corresponde a generator. Se asigna al modificador -G de CMake y especifica el generador de CMake que se va a usar. Esta propiedad también se puede usar como una macro, ${generator}, al crear otros valores de propiedad. En la actualidad, Visual Studio admite los generadores de CMake siguientes:

• "Ninja"
• "Archivos Make Unix"
• "Visual Studio 16 2019"
• "Visual Studio 16 2019 Win64"
• "Visual Studio 16 2019 ARM"
• "Visual Studio 15 2017"
• "Visual Studio 15 2017 Win64"
• "Visual Studio 15 2017 ARM"
• "Visual Studio 14 2015"
• "Visual Studio 14 2015 Win64"
• "Visual Studio 14 2015 ARM"

Como Ninja está diseñado para velocidades de compilación rápidas en lugar de flexibilidad y funcionamiento, se establece como el valor predeterminado. Pero es posible que algunos proyectos de CMake no se puedan generar correctamente mediante Ninja. Si eso ocurre, puede indicar a CMake que en su lugar genere un proyecto de Visual Studio.

Modo IntelliSense

El modo IntelliSense que usa el motor de IntelliSense. Si no se selecciona ningún modo, Visual Studio hereda el modo del conjunto de herramientas especificado.

Directorio de instalación

El directorio en el que CMake instala los destinos. Asigna a CMAKE_INSTALL_PREFIX.

Ejecutable de CMake

La ruta de acceso completa al ejecutable del programa CMake, incluidos el nombre y la extensión del archivo. Permite usar una versión personalizada de CMake con Visual Studio. Para las compilaciones remotas, especifique la ubicación de CMake en el equipo remoto.

Para las configuraciones como Linux en las que se usan compilaciones remotas, también están disponibles las opciones siguientes:

CMakeLists.txt raíz remoto

El directorio de la máquina remota que contiene el archivo raíz CMakeLists.txt.

Raíz de instalación remota

El directorio del equipo remoto en el que CMake instala los destinos. Asigna a CMAKE_INSTALL_PREFIX.

Copiar orígenes en remoto

Especifica si se deben copiar los archivos de código fuente en la máquina remota y permite especificar si se debe usar rsync o sftp.

Modificación directa del archivo CMakeSettings.json

También puede editar CMakeSettings.json de forma directa para crear configuraciones personalizadas. El Editor de configuración tiene un botón Editar JSON en la esquina superior derecha que abre el archivo para la edición.

En el ejemplo siguiente se muestra un ejemplo de configuración, que se puede usar como punto de partida:

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

IntelliSense de JSON ayuda a editar el archivo CMakeSettings.json:

El editor de JSON también le informa cuando elige opciones incompatibles.

Para más información sobre cada una de las propiedades del archivo, vea Referencia del esquema de CMakeSettings.json.

Visual Studio 2017 proporciona varias configuraciones de CMake que definen cómo se invoca CMake para crear una caché de CMake para un proyecto determinado. Para agregar una configuración nueva, haga clic en el menú desplegable Configuración de la barra de herramientas y seleccione Administrar configuraciones:

Puede elegir una de las opciones de la lista de configuraciones predefinidas:

La primera vez que seleccione una configuración, Visual Studio creará un archivo CMakeSettings.json en la carpeta raíz del proyecto. Este archivo se usa para volver a crear el archivo de caché de CMake, por ejemplo después de una operación Limpiar.

Para agregar otra configuración, haga clic en CMakeSettings.json con el botón derecho y elija Agregar configuración.

También puede editar el archivo mediante el Editor de configuración de CMake. Haga clic con el botón derecho en CMakeSettings.json en el Explorador de soluciones y seleccione Editar configuración de CMake. También puede seleccionar Administrar configuraciones en la lista desplegable de configuraciones en la parte superior de la ventana del editor.

También puede editar CMakeSettings.json de forma directa para crear configuraciones personalizadas. En el ejemplo siguiente se muestra un ejemplo de configuración, que se puede usar como punto de partida:

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

IntelliSense de JSON ayuda a editar el archivo CMakeSettings.json:

Para más información sobre cada una de las propiedades del archivo, consulte el esquema de referencia de CMakeSettings.json.