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 работает таким образом.

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

Так как вышеописанный подход не сообщает CMake, какая пользовательская команда генерирует byproduct.txt, генератор Ninja не имеет достаточной информации, чтобы добавить побочный продукт в качестве выхода любого правила. CMake 2.8.12 и выше обходят эту проблему и позволяют проектам, использующим вышеописанный подход, выполнить сборку, сгенерировав phony правила сборки, чтобы сообщить Ninja о том, что такие отсутствующие файлы нужно игнорировать. Однако это решение не позволяет 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.13.5 предупреждает, когда обнаруживает неизвестные зависимости в сборках вне исходного кода, если политика не задана, а затем использует поведение OLD. Используйте команду cmake_policy(), чтобы явно установить политику в значение OLD или NEW. Настройка политики должна быть в области действия в конце верхнего CMakeLists.txt файла проекта и имеет глобальное действие.