Proyectos de CMake en Visual Studio

CMake es una herramienta de código abierto multiplataforma para definir procesos de compilación que se ejecutan en varias plataformas. En este artículo se da por hecho que está familiarizado con CMake. Para obtener más información sobre CMake, vea la documentación de CMake. El tutorial de CMake es una buena manera de empezar a obtener más información.

Nota:

CMake se ha integrado cada vez más con Visual Studio en las últimas versiones. Para ver la documentación de su versión preferida de Visual Studio, use el control de selector Versión. Se encuentra en la parte superior de la tabla de contenido de esta página.

La compatibilidad nativa de Visual Studio con CMake permite editar, compilar y depurar proyectos de CMake en Windows, en el Subsistema de Windows para Linux (WSL) y en sistemas remotos desde la misma instancia de Visual Studio. Visual Studio consume directamente los archivos de proyecto de CMake (como CMakeLists.txt) para los propósitos de IntelliSense y la exploración. Visual Studio invoca cmake.exe directamente para la configuración y la compilación de CMake.

Instalación

El componente Herramientas de CMake en C++ para Windows se instala como parte de las cargas de trabajo Desarrollo para el escritorio con C++ y Desarrollo de Linux con C++. Se necesitan tanto el componente Herramientas de CMake en C++ para Windows como Desarrollo de Linux con C++ para el desarrollo de CMake multiplataforma.

En el instalador, se selecciona el menú desplegable Desarrollo de escritorio con C plus plus y C Herramientas de creación de C para Windows."

Para obtener más información, vea Instalación de la carga de trabajo de Linux para C++ en Visual Studio.

Integración del IDE

Al abrir una carpeta que contiene un archivo CMakeLists.txt, sucede lo siguiente.

El cuadro de diálogo ofrece estas opciones: clonar un repositorio, abrir un proyecto o una solución, abrir una carpeta local o crear un nuevo proyecto. Abra una carpeta local en la captura de pantalla.

• Visual Studio agrega elementos de CMake al menú Proyecto, con comandos para ver y editar scripts de CMake.

• En el Explorador de soluciones se muestra la estructura de carpetas y archivos.

• Visual Studio ejecuta CMake y genera el archivo de caché de CMake (CMakeCache.txt) para la configuración predeterminada. La línea de comandos de CMake se muestra en la ventana de salida, junto con otras salidas de CMake.

• En segundo plano, Visual Studio empieza a indexar los archivos de código fuente para habilitar IntelliSense, la información de exploración, la refactorización y así sucesivamente. Mientras trabaja, Visual Studio supervisa los cambios en el editor y también en el disco para mantener sincronizado su índice con los orígenes.

Nota:

A partir de visual Studio 2022, versión 17.1, versión preliminar 2, si el nivel superior CMakeLists.txt existe en una subcarpeta y no en la raíz del área de trabajo, se le pedirá si desea habilitar la integración de CMake o no. Para obtener más información, consulte Activación parcial de CMake.

Una vez que la generación de caché de CMake se ha llevado a cabo correctamente, también puede ver los proyectos organizados lógicamente por destinos. Elija el botón Seleccionar vista en la barra de herramientas del Explorador de soluciones. En la lista de Explorador de soluciones - Vistas, seleccione Vista de destinos de CMake y presione Entrar para abrir la vista de destinos:

Haga clic en el botón Mostrar todos los archivos en la parte superior del Explorador de soluciones para ver todos los resultados generados por CMake en las carpetas out/build/<config>.

Use el archivo CMakeLists.txt en cada carpeta del proyecto tal como lo haría en cualquier proyecto de CMake. Puede especificar archivos de código fuente, buscar bibliotecas, establecer opciones del compilador y del enlazador, y especificar otra información relacionada con el sistema de compilación. Para obtener más información sobre los servicios de lenguaje CMake que proporciona Visual Studio, vea Edición de archivos CMakeLists.txt.

Visual Studio usa un archivo de configuración de CMake para impulsar la generación y la compilación de la caché de CMake. Para obtener más información, vea Configuración de proyectos de CMake y Compilación de proyectos de CMake.

Para pasar argumentos a un archivo ejecutable en tiempo de depuración, puede usar otro archivo denominado launch.vs.json. Para obtener más información sobre la depuración de proyectos de CMake multiplataforma en Visual Studio, vea Depuración de proyectos de CMake.

La mayoría de las características del lenguaje C++ y de Visual Studio son compatibles con los proyectos de CMake en Visual Studio. Algunos ejemplos son:

• Editar y continuar para proyectos de CMake
• Integración de Incredibuild para proyectos de CMake
• Compatibilidad de AddressSanitizer con proyectos de CMake
• Compatibilidad con Clang/LLVM

Nota:

Para otros tipos de proyectos Abrir carpeta, se usa un archivo JSON adicional CppProperties.json. Este archivo no es relevante para los proyectos de CMake.

Configuración de proyectos de CMake

El paso de configuración de CMake genera el sistema de compilación del proyecto. Esto equivale a invocar cmake.exe desde la línea de comandos. Para obtener más información sobre el paso de configuración de CMake, consulte la documentació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. CMakeSettings.json está disponible para los clientes que usan una versión anterior de Visual Studio. Para obtener más información sobre CMakeSettings.json, consulte Personalizar la configuración de compilación de CMake.

Cuando realice cambios significativos en el archivo de configuración de CMake o en un archivo CMakeLists.txt, Visual Studio ejecutará automáticamente el paso de configuración de CMake. Puede invocar el paso de configuración manualmente: seleccione Proyecto > Configurar caché en la barra de herramientas. También puede cambiar las preferencias de configuración en Herramientas>Opciones>CMake>General.

Los ajustes de configuración de CMake son llamados. Mostrar C Realizar notificaciones de caché está seleccionado. En "Cuando la memoria caché no está actualizada:", se selecciona la opción "Nunca ejecutar el paso de configuración automáticamente".

Si el paso de configuración finaliza sin errores, la información que está disponible es lo que impulsa C++ IntelliSense y los servicios de lenguaje. También se usa esta información en las operaciones de compilación y depuración.

También puede abrir una caché de CMake existente en Visual Studio. Para obtener más información, vea Apertura de una caché existente.

Personalización de las notificaciones y los comentarios de configuración

De forma predeterminada, la mayoría de los mensajes de configuración se suprimen a menos que haya un error. Para ver todos los mensajes, seleccione Herramientas>Opciones>CMake>Habilitar salida de diagnóstico detallada de CMake.

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.

Solución de problemas de errores de caché de CMake

Si necesita más información sobre el estado de caché de CMake para diagnosticar un problema, abra el menú principal de Proyecto o el menú contextual de CMakeLists.txt en el Explorador de soluciones para ejecutar uno de estos comandos:

• Ver CMakeCache.txt abre el archivo CMakeCache.txt desde el directorio de compilación en el editor. Cualquier modificación que realice aquí para CMakeCache.txt se borra si limpia la caché. Para realizar cambios que se conserven después de limpiar la caché, vea Personalización de la configuración de CMake o Configuración y compilación con valores preestablecidos de CMake.

• Delete Cache and Reconfigure (Eliminar la caché y reconfigurar) elimina el directorio de compilación y vuelve a configurarlo a partir de una caché limpia.

• Configurar caché fuerza la ejecución del paso de generación aunque Visual Studio considere que el entorno está actualizado.

Compilar proyectos de CMake

El paso de compilación de CMake compila un árbol binario del proyecto ya generado. Esto equivale a invocar cmake --build desde la línea de comandos. Para obtener más información sobre el paso de compilación de CMake, consulte la documentación de CMake.

Para compilar un proyecto de CMake, tienes estas opciones:

1. En la barra de herramientas, busque la lista desplegable Elemento de inicio. Seleccione el destino preferido y presione F5, o bien haga clic en el botón Ejecutar en la barra de herramientas. Primero se compila el proyecto de manera automática, como una solución de Visual Studio.

2. Haga clic con el botón derecho en el destino de CMake con la Vista de destinos de CMake activa en el Explorador de soluciones y seleccione Compilar en el menú contextual.

3. En el menú principal, seleccione Compilar > Compilar todo. Asegúrese de que hay un destino de CMake seleccionado en la lista desplegable Elemento de inicio de la barra de herramientas.

Como cabría esperar, los resultados de la compilación se muestran en la ventana de Salida y en la Lista de errores.

Las advertencias de compilación de CMake sobre las conversiones que pueden dar lugar a una pérdida de datos, como la conversión de un valor flotante a un entero, son visibles. :::image-end:::

Modificación de la configuración de compilación

Visual Studio usa un archivo de configuración de CMake para impulsar las compilaciones de CMake. Los archivos de configuración de CMake encapsulan opciones de compilación, como modificadores de herramientas de compilación nativas y variables de entorno. Si CMakePresets.json es el archivo de configuración activo, consulte Configuración y compilación con valores preestablecidos de CMake. Si CMakeSettings.json es el archivo de configuración activo, consulte Personalización de la configuración de compilación de CMake. CMakePresets.json está disponible en Visual Studio 2019 versión 16.10 o posterior y es el archivo de configuración de CMake recomendado.

Depuración de proyectos de CMake

Todos los destinos de CMake ejecutables se muestran en la lista desplegable Elemento de inicio en la barra de herramientas. Para iniciar la depuración, seleccione uno y presione el botón Depurar > Iniciar depuración en la barra de herramientas. En un proyecto de CMake, la opción "Documento actual" solo es válida para los archivos .cpp.

La lista desplegable tiene estas opciones: Mostrar u ocultar destinos de depuración, documento actual, ejemplos (resaltados), box2d_tests y samples-noGUI.

Los comandos Depurar o F5 compilan primero el proyecto si se han realizado cambios desde la compilación anterior. Los cambios en el archivo de configuración de CMake (CMakePresets.json o CMakeSettings.json) o un CMakeLists.txt hacen que se vuelva a generar la caché de CMake.

Puede personalizar una sesión de depuración de CMake mediante el establecimiento de las propiedades en el archivo launch.vs.json. Para personalizar la configuración de depuración de un destino específico, selecciónelo en la lista desplegable Elemento de inicio y presione Depurar > Configuración de depuración e inicio de <active-target>. Para obtener más información sobre las sesiones de depuración de CMake, vea Configuración de sesiones de depuración de CMake.

Solo mi código para proyectos de CMake

Cuando se compila para Windows mediante el compilador de MSVC, los proyectos de CMake admiten la característica de depuración Solo mi código. Para cambiar el valor de Solo mi código, vaya a Herramientas>Opciones>Depuración>General. Para más información sobre la depuración de Solo mi código, consulte Depuración de solo el código de usuario con Solo mi código.

Editar y continuar para proyectos de CMake

Al compilar para Windows con el compilador de MSVC, los proyectos de CMake son compatibles con Editar y continuar. Agregue el código siguiente al archivo CMakeLists.txt para habilitar Editar y continuar. Para más información sobre Editar y continuar, consulte Configuración de Editar y continuar (C#, VB, C++)..

if(MSVC)
  target_compile_options(<target> PUBLIC "/ZI")
  target_link_options(<target> PUBLIC "/INCREMENTAL")
endif()

Asociación a un proyecto de CMake que se ejecuta en Linux

Visual Studio permite depurar un proceso que se ejecuta en un sistema Linux remoto o WSL y depurarlo con el depurador GDB. Para empezar, seleccione Depurar>Asociar al proceso, establezca el Tipo de conexión en SSH y seleccione el Destino de conexión en la lista de conexiones de Connection Manager. Seleccione un proceso de la lista de procesos disponibles y presione Asociar. GDB debe estar instalado en el equipo Linux. Para obtener más información sobre las conexiones SSH, consulte el Administrador de conexiones.

Las siguientes opciones están disponibles en el cuadro de diálogo: Tipo de conexión (establecido en SSH), destino de conexión (establecido en demo@ 172. 20. 60. 6) y una lista de los procesos disponibles a los que puede asociarse."

Activación parcial de CMake

En Visual Studio 2022, versión 17.1 y posteriores, la funcionalidad de CMake no se habilitará automáticamente si la carpeta raíz no contiene un archivo CMakeLists.txt. En su lugar, un cuadro de diálogo le preguntará si desea habilitar la funcionalidad de CMake para el proyecto. Si rechaza, la generación de caché de CMake no se iniciará y las configuraciones de CMake (de CMakeSettings.json o CMakePresets.json) no aparecerán en la lista desplegable de configuración. Si acepta, se le indicará un archivo de configuración de nivel de área de trabajo, CMakeWorkspaceSettings.json (almacenado en el directorio .vs) para especificar las carpetas para las que desea habilitar CMake. (Estas carpetas contienen los archivos raíz CMakeLists.txt).

Las propiedades aceptadas son:

Propiedad	Descripción
enableCMake	Habilite la integración de Visual Studio para esta área de trabajo.
sourceDirectory	Cadena o matriz de cadenas que especifican el directorio o directorios con CMakeLists.txt. Se permiten macros (como ${workspaceRoot}). Las rutas de acceso relativas se basan en la raíz del área de trabajo. Se omitirán los directorios fuera del área de trabajo actual.

Puede acceder a CMakeWorkspaceSettings.json través del comando de menú proyecto>Configuración de área de trabajo de CMake en cualquier momento, incluso si la funcionalidad de CMake está deshabilitada actualmente.

Apertura de una caché existente

Al abrir un archivo de caché de CMake existente (CMakeCache.txt), Visual Studio no intenta administrar la caché y el árbol de compilación automáticamente. Las herramientas personalizadas o preferidas tienen un control completo sobre cómo CMake configura el proyecto.

Puede agregar una caché de CMake existente a un proyecto abierto. Se hace de la misma manera que para agregar una nueva configuración. Para obtener más información, consulte nuestra entrada de blog sobre cómo abrir una caché existente en Visual Studio.

Nota:

La experiencia de caché existente predeterminada depende de cmake-server, que se quitó en la versión 3.20 de CMake. Para seguir usando la funcionalidad de caché existente en la versión 16.10 y posteriores de Visual Studio 2019, siga uno de estos pasos:

• Instale manualmente la versión 3.19 de CMake o una inferior. A continuación, establezca la propiedad cmakeExecutable en la configuración de caché existente para usar esa versión de CMake.
• En la configuración de caché existente, establezca la propiedad cacheGenerationCommand para permitir que Visual Studio solicite los archivos de API basadas en archivos de CMake necesarios. Para obtener más información sobre esta propiedad, consulte la referencia de CMakeSettings.json.
• Use un archivo de consulta para solicitar los archivos de API basadas en archivos de CMake al generar la memoria caché antes de que se abra en Visual Studio. Para obtener instrucciones sobre el archivo de consulta, vea la sección siguiente, Solución avanzada de problemas de caché de CMake.

Solución avanzada de problemas de caché de CMake

Visual Studio usa la API basada en archivos de CMake (en la versión 3.14 y posteriores) para rellenar el editor con información específica de la estructura del proyecto. Para obtener más información, vea la entrada de blog del equipo de C++ sobre las áreas de trabajo con varias raíces y la API basada en archivos.

Antes de generar la caché de CMake, es posible que las herramientas personalizadas o preferidas necesiten crear un archivo de consulta denominado .cmake/api/v1/query/client-MicrosoftVS/query.json en la carpeta de salida de la compilación (la carpeta que contiene CMakeCache.txt). El archivo de consulta debe contener lo siguiente:

{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]}

Cuando las herramientas personalizadas o preferidas generan la memoria caché, CMake coloca los archivos en .cmake/api/v1/response, que Visual Studio usa para rellenar el editor con información específica de la estructura del proyecto.

Edición de archivos CMakeLists.txt

Para editar un archivo CMakeLists.txt, haga clic con el botón derecho en el archivo en el Explorador de soluciones y seleccione Abrir. Si realiza cambios en el archivo, aparece una barra de estado de color amarillo y le informa de que IntelliSense se va a actualizar. Le ofrece la oportunidad de cancelar la operación de actualización. Para obtener información sobre CMakeLists.txt, consulte la documentación de CMake.

Contiene el proyecto de líneas (hello-cmake), add_subdirectory (pruebas), add_executable (hello hello.cpp) e instalación (TARGETS hello DESTINATION hello/bin). Un mensaje en la parte superior de la ventana indica que c más información de IntelliSense se actualizará después de que C Complete la generación de la memoria caché.

Tan pronto como se guarde el archivo, se vuelve a ejecutar el paso de configuración de manera automática y se muestra la información en la ventana Salida. Los errores y las advertencias se muestran en la Lista de errores o en la ventana Salida. Haga doble clic en un error en la Lista de errores para navegar a la línea incorrecta en CMakeLists.txt.

Se resalta un mensaje de error C Make en la línea 3 de CMakeLists.txt. Los detalles son que C Make no pudo encontrar un archivo de configuración de paquete proporcionado por sqlite3. C Make lo buscaron en CMAKE_MODULE_PATH pero no lo encontraron. La sugerencia es agregar el prefijo de instalación "sqlite3" a CMAKE_PREFIX_PATH o establecer sqlite3_DIR en un directorio que contenga sqlite3Config.cmake y/o sqlitet3-config.cmake.

Servicios de lenguaje para CMake

Los servicios de lenguaje para CMake están disponibles en Visual Studio 2019 versión 16.5 o posteriores. Las características de navegación de código, como Ir a definición, Ver la definición sin salir y Buscar todas las referencias son ahora compatibles con variables, funciones y destinos en archivos de script de CMake. Para obtener más información, vea Navegación de código para scripts de CMake.

Se muestran los resultados de dónde se muestran los SUPERTUX_SOURCES_CXX. Por ejemplo, en list(SORT SSUPERTUX_SOURCES_CXX), file(GLOB SUPERTUX_SOURCES_CXX) y así sucesivamente.

Manipulación de proyectos de CMake

La manipulación de proyectos de CMake está disponible Visual Studio 2019 versión 16.5 o posteriores. La manipulación de proyectos le permite agregar, quitar o cambiar el nombre de los archivos de código fuente y los destinos de los proyectos de CMake sin modificar manualmente los scripts de CMake. Al agregar o quitar archivos desde el Explorador de soluciones, Visual Studio editará automáticamente el proyecto de CMake. Puede haber más de un lugar donde tenga sentido agregar o quitar una referencia a un script de CMake. Si es así, Visual Studio le pregunta dónde desea realizar el cambio y muestra una vista previa de los cambios propuestos. Para obtener instrucciones paso a paso, vea Adición, eliminación y cambio de nombre de archivos y destinos en proyectos de CMake.

Una vista de árbol muestra CMakeLists.txt, bajo los cuales hay dos elementos: add_executable y set. Se comprueba el conjunto. La ventana de vista previa muestra dónde se realizarán los cambios. El conjunto de líneas (PROJECT_SRC "CmakeProject4.cpp" "CMakeProject4.h" muestra "Demo.cpp" resaltado antes del paréntesis de cierre. El botón Aplicar acepta el cambio o puede presionar cancelar.

IntelliSense para proyectos de CMake

De forma predeterminada, Visual Studio usa el modo de IntelliSense que coincide con la arquitectura del compilador y del destino especificada en la configuración activa de CMake.

Si CMakePresets.json es el archivo de configuración activo de CMake, se pueden especificar opciones de IntelliSense con intelliSenseMode y intelliSenseOptions en la asignación de proveedor de configuración de Visual Studio. Para obtener más información, consulte la referencia de asignación de proveedor de configuración de Visual Studio.

Si CMakeSettings.json es el archivo de configuración de CMake activo, puede especificar las opciones de IntelliSense con intelliSenseMode en CMakeSettings.json. Para más información, consulte la referencia de CMakeSettings.json.

Configuración de IntelliSense con archivos de cadena de herramientas de CMake

En Visual Studio 2019, versión 16.9 y posteriores, Visual Studio configura automáticamente IntelliSense en proyectos de CMake basados en variables de CMake cuando se usa un archivo de cadena de herramientas de CMake. Para obtener más información, consulte Configuración de IntelliSense con archivos de cadena de herramientas de CMake.

Integración de vcpkg

Los proyectos de CMake abiertos en Visual Studio se integran con vcpkg, un administrador de dependencias de C/C++ multiplataforma. Antes de usar vcpkg con Visual Studio, debe ejecutar vcpkg integrate install. Para obtener instrucciones y más información sobre vcpkg, consulte:

• Instalación y uso de paquetes con CMake en Visual Studio
• vcpkg en proyectos de CMake

Si CMakeSettings.json es el archivo de configuración activo, Visual Studio pasará automáticamente el archivo de cadena de herramientas de vcpkg (vcpkg.cmake) a CMake. Este comportamiento se deshabilita automáticamente cuando se especifica cualquier otra cadena de herramientas en la configuración de los valores de CMake.

Si CMakePresets.json es el archivo de configuración activo, deberá establecer la ruta de acceso a vcpkg.cmake en CMakePresets.json. Se recomienda usar la variable de entorno VCPKG_ROOT en lugar de una ruta de acceso absoluta para que el archivo se pueda compartir. Para obtener más información, vea Habilitación de la integración de vcpkg con valores preestablecidos de CMake. CMakePresets.json está disponible en Visual Studio 2019 versión 16.10 o posterior y es el archivo de configuración de CMake recomendado.

Ejecutar CMake desde la línea de comandos

Si CMakePresets.json es el archivo de configuración de CMake activo, puede reproducir fácilmente las compilaciones locales fuera de Visual Studio. Para obtener más información, consulte Ejecución de CMake desde la línea de comandos o una canalización de integración continua. CMakePresets.json es admitido con Visual Studio 2019, versión 16.10 o posterior, y es el archivo de configuración de CMake recomendado.

Si CMakeSettings.json es el archivo de configuración activo de CMake, deberá pasar manualmente los argumentos codificados en el archivo CMakeSettings.json a CMake. Si ha instalado CMake desde el instalador de Visual Studio, puede ejecutarlo desde la línea de comandos siguiendo estos pasos:

1. Ejecute el archivo vsdevcmd.bat adecuado (x86/x64). Para obtener más información, vea el artículo sobre cómo compilar en la línea de comandos.

2. Cambie a la carpeta de salida.

3. Ejecute CMake para compilar o configurar la aplicación.

Consulte también

Tutorial de: Creación de proyectos multiplataforma de C++ en Visual Studio
Configuración de un proyecto de CMake en Linux
Conexión al equipo remoto de Linux
Personalización de la configuración de compilación de CMake
Referencia del esquema CMakeSettings.json
Configuración de sesiones de depuración de CMake
Implementación, ejecución y depuración del proyecto de Linux
Referencia de configuración predefinida de CMake
vcpkg en proyectos de CMake
Instalación y uso de paquetes con CMake en Visual Studio