CMP0058

Ninja требует явного указания побочных продуктов пользовательских команд.

Когда промежуточный файл, сгенерированный во время сборки, используется дорогой операцией или большой деревом зависимостей, можно уменьшить объём работы при инкрементальной пересборке, обновляя метку времени файла только при изменении его содержимого. В этом подходе правило генерации должно иметь отдельный выходной файл, который всегда обновляется с новым временем, более поздним, чем любые зависимости правила, чтобы инструмент сборки повторно выполнял правило только при изменении входных данных. Мы называем отдельный выходной файл свидетелем правила, а сгенерированный файл — побочным продуктом правила.

Побочные продукты не могут быть перечислены в качестве выходных данных, так как их метки времени могут быть старше, чем входные данные. Ни один инструмент сборки (например, make) который существовал на момент разработки CMake, не имеет возможности выразить побочные продукты. Поэтому версии CMake до 3.2 не имели возможности их указать. Проекты обычно оставляли побочные продукты не объявленными в правилах, которые их генерируют. Например:

add_custom_command(
  OUTPUT witness.txt
  COMMAND ${CMAKE_COMMAND} -E copy_if_different
          ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
          byproduct.txt # timestamp may not change
  COMMAND ${CMAKE_COMMAND} -E touch witness.txt
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
  )
add_custom_target(Provider DEPENDS witness.txt)
add_custom_command(
  OUTPUT generated.c
  COMMAND expensive-task -i byproduct.txt -o generated.c
  DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt
  )
add_library(Consumer generated.c)
add_dependencies(Consumer Provider)

Это работает хорошо для всех генераторов, кроме Ninja. Инструмент сборки Ninja видит правило, которое перечисляет byproduct.txt в качестве зависимости, и нет правила, которое перечисляет его в качестве выходного. Тогда Ninja жалуется, что нет способа удовлетворить зависимость и останавливает сборку, даже если существуют зависимости только по порядку, которые гарантируют, что byproduct.txt будет существовать до того, как его потребители его потребуют. Подробнее об этой проблеме см. Ninja Issue 760.

Вместо того, чтобы оставлять побочные продукты необъявленными в правилах, которые их генерируют, Ninja ожидает, что побочные продукты будут перечислены вместе с другими выходными данными. Такие правила могут быть помечены с помощью restat опцией, которая сообщает Ninja проверять метки времени выходных данных после выполнения правил. Это предотвращает ненужную пересборку зависимых от побочных продуктов, метки времени которых не изменились.

Поскольку вышеуказанный подход не сообщает CMake, какая пользовательская команда генерирует byproduct.txt, генератор Ninja не имеет достаточной информации, чтобы добавить побочный продукт в качестве выходного для любого правила. CMake 2.8.12 и выше обходят эту проблему, разрешая проектам, использующим вышеуказанный подход, строить, генерируя phony правила сборки, чтобы сообщить Ninja, что он должен игнорировать такие недостающие файлы. Однако это решение обходит проблему обнаружения действительно недостающей зависимости. Оно также плохо работает при сборке в исходном каталоге, где каждая зависимость пользовательских команд, даже от исходных файлов, должна обрабатываться таким образом, так как CMake не имеет достаточной информации, чтобы знать, какие файлы генерируются как побочные продукты пользовательских команд.

CMake 3.2 ввёл BYPRODUCTS опцию для команд add_custom_command() и add_custom_target(). Эта опция позволяет явно указывать побочные продукты:

add_custom_command(
  OUTPUT witness.txt
  BYPRODUCTS byproduct.txt # explicit byproduct specification
  COMMAND ${CMAKE_COMMAND} -E copy_if_different
          ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
          byproduct.txt # timestamp may not change
...

Опция BYPRODUCTS используется генератором Ninja для перечисления побочных продуктов среди выходных данных пользовательских команд, которые их генерируют, и игнорируется другими генераторами.

CMake 3.3 и выше предпочитают требовать от проектов явного указания побочных продуктов пользовательских команд, чтобы избежать использования обходного пути phony правила. Политика CMP0058 была введена для обеспечения совместимости с существующими проектами, которые по-прежнему нуждаются в этом обходном пути.

Эта политика не оказывает влияния на генераторы, кроме Ninja. Поведение OLD этой политики — генерировать Ninja phony правила для неизвестных зависимостей в дереве сборки. Поведение NEW этой политики — не генерировать их и вместо этого потребовать от проектов явного указания пользовательских команд BYPRODUCTS.

Эта политика была введена в версии CMake 3.3. Версия CMake 3.7.2 предупреждает при обнаружении неизвестных зависимостей в сборке вне исходного каталога, если политика не задана, а затем использует поведение OLD. Используйте команду cmake_policy(), чтобы явно установить политику в OLD или NEW. Настройка политики должна быть в рамках действия верхнего уровня CMakeLists.txt файла проекта и имеет глобальный эффект.