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 таким образом см. в обсуждении этой проблемы в Ninja Issue 760.

Вместо того, чтобы оставлять побочные продукты не объявленными в правилах, которые их генерируют, 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.15.7 предупреждает, когда обнаруживает неизвестные зависимости в сборках вне исходного кода, если политика не задана, а затем использует поведение OLD. Используйте команду cmake_policy(), чтобы явно установить политику на OLD или NEW. Настройка политики должна быть в области действия в конце верхнего уровня CMakeLists.txt файла проекта и имеет глобальное действие.