Как победить CMake: отладка CMake-скриптов

Я много работаю с CMake. И периодически сталкиваюсь с довольно сложными и запутанными CMake-скриптами. Долгое время я использовал логи, чтобы разобраться в их работе и выполнить отладку. Позже обнаружил, что в CMake есть встроенный отладчик и профилировщик, которые сильно упрощают процесс отладки. Кажется, не все знают об их существовании и о том, как с ними работать, поэтому я решил написать эту статью.

Отладка CMake-файлов

Начиная с версии 3.27 и выше, в CMake появилась возможность отладки.

Скачать нужную версию CMake можно отсюда ^[1] (или собрать из исходников ^[2]). Более новую версию CMake допустимо использовать, даже если ваши CMake-файлы написаны для старой версии (но будьте осторожны). 

Если по какой-то причине вы не можете использовать CMake 3.27 и выше, то читайте вторую половину статьи ^[3].

Как настроить и использовать отладчик, я покажу на примере VSCode. Но полученную информацию вы сможете применить и в других IDE (например, CLion ^[4] и Visual Studio ^[5])

Чтобы запустить отладку в VSCode:

1. Установите расширение CMake Tools ^[6].

2. Откройте необходимый вам проект.

3. Нажмите Ctrl+Shift+P.

4. В появившемся окне введите cmake debugger.

5. После чего вы должны увидеть два пункта меню:

   

   Разница между пунктами только в том, что Delete Cache… удаляет файл CMakeCache.txt и выполняет повторную конфигурацию проекта.

6. Выберите необходимый вариант и нажмите Enter.

7. VSCode может дополнительно попросить указать компилятор и путь к исходникам. После этого отладчик должен запуститься.

Теперь вы можете пошагово отлаживать код, устанавливать breakpoint’ы и просматривать значения переменных:

К сожалению, с помощью отладчика нельзя отладить генераторные выражения.

Если отладка не запустилась

Если отладка не запускается или завершается с непонятной ошибкой, откройте вкладку OUTPUT в VSCode. Там выводится CMake-команда, которую использует отладчик:

По сути, плагин просто запускает cmake с необходимыми для отладки флагами, а затем подключается к его отладчику по DAP ^[7].

Обратите внимание на пути после флагов -S и -B:

• -S указывает на папку с исходным кодом проекта;

• -B указывает на папку, куда помещаются файлы сборки.

Если эти пути отличаются от ваших, то их можно исправить в настройках VSCode. Для этого установите значения cmake.sourceDirectory и cmake.buildDirectory соответственно.

Также обратите внимание на флаг -G. Он определяет, какой используется генератор сборочной системы ^[8] (Unix Makefiles, Ninja и другие). Его можно настроить с помощью опции cmake.generator в VSCode.

Если сборка вашего CMake-проекта должна запускаться с дополнительными параметрами, то необходимо перечислить их в cmake.configureArgs:

Или собрать проект привычным способом, а затем запустить отладчик, выбрав CMake: Configure with CMake Debugger. В этом случае отладчик будет работать с уже сконфигурированным проектом и переменными, сохраненными в CMakeCache.txt.

Если все настроено правильно, но отладка так и не заработала, сообщите об этом в комментариях — попробуем разобраться вместе.

Профилирование CMake

С версии CMake 3.18 также доступен профилировщик. С его помощью можно проанализировать последовательность выполнения команд, просмотреть вложенные вызовы и измерить время их работы.

Чтобы включить профилирование, добавьте в вашу команду генерации сборочной системы ^[9] CMake следующие опции: --profiling-format=google-trace и --profiling-output=fileName.

Например, в результате вызова этой команды будет сгенерирован файл с именем trace:

cmake -B my_build --profiling-format=google-trace --profiling-output=trace

Для просмотра trace-файла можно использовать любой chrome-based браузер или сайт ui.perfetto.dev ^[10]. 

Я покажу на примере Chrome. Откройте браузер, введите в адресной строке about:tracing и нажмите Enter. На открывшейся странице, нажмите кнопку Load и выберите trace-файл.

После этого файл должен открыться, и вы сможете просмотреть трейс:

Если есть темы в CMake, которые вызывают у вас боль, пишите в комментариях, и я постараюсь рассказать о них в следующих статьях.