Skip to content
TheChatArchiveThe Chat Archive
gpt-4o-2024-05-13· OpenAIAi2 WildChat-4.8M (AI2)

Ты технический писатель. Перефразируй "В отличии от большинства других макросов…

  1. User

    Ты технический писатель. Перефразируй "В отличии от большинства других макросов bob.make, относительный порядок базовых управляющих конструкций имеет значение. IF видит то значение переменной, которое было выставлено раньше в bob.make, и не видит то, которое будет выставлено ниже по тексту. Однако, если установка переменной меняет свойства модуля или его команд, она может повилять и на конструкции, написанные выше по тексту"

  2. Assistant

    В отличие от большинства других макросов в bob.make, относительная последовательность базовых управляющих конструкций имеет значение. Команда IF интерпретирует текущее значение переменной, установленное выше по тексту, и не видит будущие изменения, расположенные ниже. Однако, если установка переменной влияет на свойства модуля или его команд, это может отразиться и на уже написанных выше конструкциях.

  3. User

    Перефразируй " INCLUDE Система сборки bob make поддерживает текстовые включения макросом INCLUDE(<full_file_name>). Текст из файла, переданного параметром будет подставлен вместо INCLUDE и интерпретирован.

    Соответственно этот текст:

    Будет относиться к тому же скоупу, что и макрос INCLUDE. Переменные, определённые в тексте будут определять модульные переменные, если INCLUDE размещён в модуле и будут видны в условных конструкциях и параметрах других макросов ниже этого макроса. Переменные, определённые выше INCLUDE будут доступны в параметрах макросов включённого файла, включая условных конструкциях Сейчас по умолчанию включения файлов обрабатываются каждый раз, когда встречаются при интерпретации bob.make и включенных в него файлов. В частности макросы SET_APPEND во включенном файле будут вызваны столько раз, сколько встрется файл внутри одного bob.make. Это может привести к неоправданному росту значений переменных. Изменить поведение на однократную обработку для каждого начального bob.make можно макросом INCLUDE_ONCE. INCLUDE внутри мультимодуля, независимо от реальной реализации, действует так, словно все текстовые ключения сделаны до порождения вариантов мультимодуля. Т.е. конструкции из включенного файла будут интерптетированы во всех вариантах мультимодуля. Параметром макросом должно быть полное имя, с указанием ${DIR_ROOT}/ как принадлежность к дереву исходных файлов. "

  4. Assistant

    INCLUDE Система сборки bob make поддерживает текстовые включения через макрос INCLUDE(<full_file_name>). Текст из указанного файла будет вставлен на место макроса INCLUDE и затем интерпретирован.

    Таким образом, вставленный текст:

    Будет относиться к тому же скоупу, что и макрос INCLUDE. Переменные, определённые в тексте, будут становиться модульными переменными, если INCLUDE размещён в модуле, и будут видны в условных конструкциях и параметрах других макросов, находящихся ниже по тексту. Переменные, определённые выше INCLUDE, будут доступны в параметрах макросов включённого файла, включая условные конструкции. По умолчанию на данный момент включаемые файлы обрабатываются каждый раз, когда встречаются при интерпретации bob.make и включённых в него файлов. В частности, макросы SET_APPEND в включённом файле будут выполняться столько раз, сколько раз файл включён в bob.make. Это может привести к избыточному росту значений переменных. Чтобы изменить поведение на однократную обработку файлов для каждого начального bob.make, можно использовать макрос INCLUDE_ONCE. В контексте мультимодуля любой INCLUDE работает так, как если бы все текстовые включения были выполнены до генерации вариантов мультимодуля. То есть конструкции из включённого файла будут интерпретированы во всех вариантах мультимодуля. Параметром INCLUDE должно быть полное имя файла, с указанием ${DIR_ROOT}/ как принадлежность к дереву исходных файлов.

  5. User

    Перефразируй "Тестовые включения могут приводить к тому, что один и тот же файл будет по разным путям от основного bob.make включен несколько раз. Это будет приводить к замедлению работы а также, возможно, к дублированию значений при вызове макроса SET_APPEND.

    Чтобы избежать этого рекомендуется использовать макрос INCLUDE_ONCE(). Файл, в котором написан такой макрос будет обработан только один раз для каждого bob.make-файла. Остальные его включения при обработке этого bob.make будут проигнорированы.

    Макрос без параметров или с параметром yes включает однократную обработку файла. Макрос с параметром no выключает однократную обработку файла. Это может быть полезно чтобы зафиксировать явно, что файл предназначен для многократного включения. И особенно это будет полезно при смене поведения INCLUDE по-умолчанию."

  6. Assistant

    Повторные включения могут вызвать ситуацию, когда один и тот же файл будет включён несколько раз через различные пути от основного bob.make, что приведёт к замедлению работы и потенциальному дублированию значений при использовании макроса SET_APPEND.

    Для предотвращения этого рекомендуется применять макрос INCLUDE_ONCE(). Файл, содержащий этот макрос, будет обрабатываться только один раз для каждого bob.make-файла. Все последующие включения этого файла в рамках обработки текущего bob.make будут игнорироваться.

    Макрос INCLUDE_ONCE без параметров или с параметром yes активирует однократную обработку файла. Макрос INCLUDE_ONCE с параметром no отключает однократную обработку файла. Это может быть полезно для явного обозначения того, что файл предназначен для многократного включения, особенно если поведение INCLUDE по умолчанию изменится.

  7. User

    "Где бы макрос INCLUDE_ONCE не исполнился в файле, этот файл не будет интерпретирован второй раз. Однако рекомендуется писать макрос в самом начале файла и настоятельно не рекомендуется ставить его под IF."

  8. Assistant

    Независимо от того, где в файле выполнен макрос INCLUDE_ONCE, этот файл не будет интерпретирован повторно. Однако рекомендуется размещать этот макрос в самом начале файла и настоятельно не рекомендуется вставлять его внутри условных конструкций (IF).

  9. User

    "Задаёт или изменяет значение переменной, перетирая то значение, которое возможно было выставлено раньше.

    SET_APPEND"

  10. Assistant

    "Задает или изменяет значение переменной, перезаписывая любое ранее установленное значение.

    SET_APPEND"

  11. User

    "Добавляет значение к переменной. Существующее значение могло быть определено в глобальной конфигурации сборки, например SET_APPEND(CFLAGS -fno-omit-frame-pointer) добавит к глобально определённым для C++ и C модулей флагам тот, что требуется текущему модулю."

  12. Assistant

    "Добавляет значение к переменной. Существующее значение могло быть установлено в глобальной конфигурации сборки. Например, команда SET_APPEND(CFLAGS -fno-omit-frame-pointer) добавит указанный флаг к глобально определённым флагам для модулей C++ и C, обеспечивая требуемый флаг для текущего модуля."

  13. User

    "Задаёт значение по умолчанию для переменной. В отличие от SET(VarName VarValue) установит запрошенное значение переменной только если для данной переменной значение ещё нигде не было определено."

  14. Assistant

    "Задает значение по умолчанию для переменной. В отличие от SET(VarName VarValue), этот макрос установит значение переменной только в том случае, если значение для данной переменной ещё нигде не было определено."

  15. User

    "Взводит либо сбрасывает переменную, используемую в качестве флага. Эквивалентно SET(VarName yes)/SET(VarName no). "

  16. Assistant

    "Устанавливает или сбрасывает значение переменной, используемой в качестве флага. Эквивалентно командам SET(VarName yes) / SET(VarName no)."

  17. User

    "Позволяет исполнять или не исполнять макросы в зависимости от условий. Работает аналогично похожим конструкциям в императивных языках программирования.

    В качестве выражений можно использовать:

    • VAR_NAME, $VAR_NAME, ${VAR_NAME} - будет проверено значение переменной. Пустое значение или имя не установленной нигде переменной интерпретируется как false. В остальных случаях значение интерпретируется с помощью функций из util:
      • IsTrue: true, t, yes, y, on, 1, da.
      • IsFalse: false, f, no, n, off, 0, net.
    • NOT Expr, Expr AND Expr, Expr OR Expr - логические выражения (приоритеты операций соблюдаются правильно: NOT, AND, OR).
    • DEFINED VAR_NAME - проверка определена ли переменная.
    • ISNUM SomeStrValue, ISNUM $VAR_NAME, ISNUM ${VAR_NAME} - проверка является ли содержимое переменной целочисленным значением.
    • ==, != - сравнение значений переменных и/или строковых значений
    • MATCHES - бинарный оператор проверяющий, что значение правого операнда является подстрокой в значении левого.
    • VERSION_GT, VERSION_GE, VERSION_LT, VERSION_LE - бинарные операторы сравнения версии. Учитывают не более трёх численных сегментов, разделённых точкой или дефисом. Например, 3.5.17, 5.2, 4-12, 1-5-17.
    • >, <, >=, <= - бинарные операторы сравнения целых чисел."
  18. Assistant

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

    В качестве выражений можно использовать:

    • VAR_NAME, $VAR_NAME, ${VAR_NAME} - проверяется значение переменной. Пустое значение или имя переменной, которая не была нигде определена, интерпретируются как false. В остальных случаях значение интерпретируется с помощью функций из util:
      • IsTrue: true, t, yes, y, on, 1, da.
      • IsFalse: false, f, no, n, off, 0, net.
    • NOT Expr, Expr AND Expr, Expr OR Expr - логические выражения (приоритеты операций соблюдаются правильно: NOT, AND, OR).
    • DEFINED VAR_NAME - проверка, определена ли переменная.
    • ISNUM SomeStrValue, ISNUM $VAR_NAME, ISNUM ${VAR_NAME} - проверка, является ли содержимое переменной целочисленным значением.
    • ==, != - сравнение значений переменных и/или строковых значений.
    • MATCHES - бинарный оператор, проверяющий, что значение правого операнда является подстрокой в значении левого.
    • VERSION_GT, VERSION_GE, VERSION_LT, VERSION_LE - бинарные операторы сравнения версий. Учитывают не более трёх числовых сегментов, разделённых точкой или дефисом. Например, 3.5.17, 5.2, 4-12, 1-5-17.
    • >, <, >=, <= - бинарные операторы сравнения целых чисел."
  19. User

    "Работоспособность этой конструкции не гарантируется. Это пока может работать для некоторых типов модулей, а для других работать не будет. Мы не рекомендуем использовать разные типы модуля по однному пути в разных случаях в принципе, но если это необходимо, то правильный способ - убрать под IF весь модуль и вынести общую часть через INCLUDE."

  20. Assistant

    "Работоспособность этой конструкции не гарантируется. В настоящее время она может работать для некоторых типов модулей, но не для всех. Мы не рекомендуем использовать разные типы модулей по одному пути в различных ситуациях. Однако, если это необходимо, правильный подход - обернуть весь модуль в условную конструкцию IF и вынести общую часть через INCLUDE."

  21. User

    "- Если KIND указан как STATUS или не указан, то сообщение выводится предупреждение.

    • Если KIND указан как FATAL_ERROR, то сообщение выводится как configure-ошибка и сборка останавливается."
  22. Assistant
    • Если KIND указан как STATUS или не указан, то сообщение выводится как предупреждение.
    • Если KIND указан как FATAL_ERROR, то сообщение выводится как ошибка конфигурации и сборка останавливается.
  23. User

    "Выдать предупреждение или ошибку, если модуль попал в сборку в нарушение условий, выраженных COND_VARS.

    • Макрос BUILD_ONLY_IF выдаёт ошибку, если все переменные COND_VARS не определены или имеют значение ложь (false, f, no, off, 0) и, соответственно, не выдаёт, если хотя бы для одной переменной это не выполнено.
    • Макрос NO_BUILD_IF выдаёт ошибку, если хотя бы одна переменная определена и не имеет значение ложь (т.е. значение отличное от false, f, no, off, 0)."
  24. Assistant

    "Выдает предупреждение или ошибку, если модуль попал в сборку, нарушая условия, выраженные в COND_VARS.

    • Макрос BUILD_ONLY_IF выдает ошибку, если все переменные COND_VARS не определены или имеют значение ложь (false, f, no, off, 0). В противном случае ошибка не выдается.
    • Макрос NO_BUILD_IF выдает ошибку, если хотя бы одна переменная из COND_VARS определена и не имеет значение ложь (т.е. значение отличается от false, f, no, off, 0)."
  25. User

    "Параметры:

    • STRICT (режим по умолчанию) управляет интерпретацией bob.make при нарушении условий. Если выставлен, то модуль и все варианты RECURSE в его bob.make будет проигнорированы. Это приведёт к тому, что модуль не будет собираться и станет недоступен для зависимостей по PEERDIR и DEPENDS. Также не станут собираться модули, достижимые только от этого по RECURSE, например его тесты.
    • FATAL_ERROR управляет тем, должна ли выдаваться ошибка или только предупреждение при нарушении условий. Он также безусловно включает STRICT-режим интепретации (см.выше).
    • WARNING не влияет на сборку, только выдаёт configure warning при нарушении условий."
  26. Assistant

    Параметры:

    • STRICT (режим по умолчанию) управляет интерпретацией bob.make при нарушении условий. Если установлен, модуль и все варианты, указанные в его секции RECURSE, будут проигнорированы. Это приведёт к тому, что модуль не будет собираться и станет недоступен для зависимостей, определённых через PEERDIR и DEPENDS. Также не будут собираться модули, достижимые только через данный модуль по RECURSE, например его тесты.
    • FATAL_ERROR определяет, должна ли выдаваться ошибка или только предупреждение при нарушении условий. Этот параметр также безусловно включает STRICT-режим интерпретации (см. выше).
    • WARNING не влияет на сборку, а только выдает предупреждение (configure warning) при нарушении условий.
  27. User

    "Эти макросы по умолчанию работают в режиме STRICT. В случае WARNING будет лишь выдано предупреждение на консоль, и сборка продолжится. Модуль либо соберётся в запрещённой конфигурации, либо случится ошибка сборки.

    В случае с FATAL_ERROR или STRICT модуль будет исключён из сборки с соответственно configure-ошибкой или предупреждением. PEERDIR-зависимости на такой модуль выдадут дополнительные configure-ошибки. Если будут проигнорированы с помощью параметра -k (--keep-going), то возникнут ошибки линковки."

  28. Assistant

    Эти макросы по умолчанию работают в режиме STRICT. В случае использования параметра WARNING будет выдано только предупреждение на консоль, и сборка продолжится. Модуль либо соберется в запрещенной конфигурации, либо произойдет ошибка сборки.

    В случае использования параметров FATAL_ERROR или STRICT, модуль будет исключен из сборки с соответствующей ошибкой конфигурации или предупреждением. Зависимости через PEERDIR на такой модуль вызовут дополнительные ошибки конфигурации. Если такие ошибки будут проигнорированы с помощью параметра -k (--keep-going), то произойдут ошибки на этапе линковки.

  29. User

    "Позволяет указать владельца кода в данной директории. Владелец автоматически добавляется во все ревью, затрагивающие код, сборка которого описывается в данном bob.make файле. Таким кодом считается код, из которого строится модуль, описанный в данном bob.make, либо сам bob.make файл, если в нём нет модулей, а только перечисление подпроектов через RECURSE.

    При указании имени пользователя используется логин. Группы описываются в самой проекте в папке [groups]

    Данный макрос должен использоваться обязательно. При этом настоятельно рекомендуется использовать группы, а не отдельных людей, чтобы не возникали ситуации, когда, некоторый код поддерживается бывшим сотрудником (т.е. никем).

    Для нахождения владельцев кода в директориях без собственного bob.make(т.е. которые напрямую не указаны ни в одном bob.make) берётся первый найденный bob.make выше по иерархии директорий. Если в первом найденном bob.make не будет указан OWNER, то директория будет считаться бесхозной, даже если еще выше по иерархии есть bob.make с указанным OWNER."

  30. Assistant

    "Позволяет указать владельца кода в данной директории. Владелец автоматически добавляется во все ревью, касающиеся кода, сборка которого описана в данном bob.make файле. Таким кодом считается код, из которого строится модуль, описанный в данном bob.make, либо сам bob.make файл, если он содержит только перечисление подпроектов через RECURSE, но не содержит модулей.

    При указании владельца используется логин пользователя. Группы описываются в проекте в папке [groups].

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

    Для определения владельцев кода в директориях без собственного bob.make (т.е. которые напрямую не указаны ни в одном bob.make), берется первый найденный bob.make выше по иерархии директорий. Если в первом найденном bob.make не будет указан OWNER, то директория будет считаться бесхозной, даже если еще выше по иерархии есть bob.make с указанным OWNER."

  31. User

    Перефразируй "Параметры и их семантика полностью аналогичны макросу OWNER.

    Позволяет указать отдельную группу людей, которые будут получать оповещения об изменениях в коде, сборка которого описывается данным bob.make файлом. Данный макрос не налагает на описанных в нём людей ответственности, связанной с владением кодом, но позволяет отслеживать изменения. В будущем планируются доработки, позволяющие подписчикам более гибко управлять нотификациями от разных проектов."

  32. Assistant

    "Параметры и их семантика полностью аналогичны макросу OWNER.

    Позволяет указать отдельную группу людей, которые будут получать уведомления о изменениях в коде, сборка которого описана в данном bob.make файле. Этот макрос не накладывает на указанных людей ответственность за владение кодом, но позволяет им отслеживать изменения. В будущем планируется внедрение доработок, позволяющих подписчикам более гибко управлять уведомлениями от различных проектов."

  33. User

    "Добавляет к списку стартовых целей сборки проекты по указанным путям, если текущая директория находится в списке стартовых целей. Данные макросы не имеют никакого эффекта, если текущий проект попал в сборку через PEERDIR, DEPENDS или как инструмент сборки (через RUN_PROGRAM либо из реализации специфичного макроса, использующего проект из аркадии в качестве шага сборки).

    При вызове ya make some/project/subdir another/project/dir изначальный список стартовых проектов задаётся через аргументы командной строки, в процессе чтения ya.make файлов к стартовым целям будут добавляться директории, добавленные через одну из форм макроса RECURSE. Данный процесс продолжается рекурсивно.

    Простейшая и наиболее часто используемая форма макроса RECURSE принимает в качестве аргументов список относительных путей и интерпретирует их как пути относительно директории, в которой лежит интерпретируемый в данный момент ya.make файл.

    Для подключения проектов с тестами рекомендуется использовать форму RECURSE_FOR_TESTS, которая не добавляет перечисленные в ней проекты в сборку, если не запрошена сборка тестов. Так же, как и в случае простейшей формы макроса, принимаемые пути интерпретируются как пути относительно директории интерпретируемого в данный момент ya.make файла.

    Если требуется задать путь, лежащий за пределами текущей директории, то используется форма RECURSE_ROOT_RELATIVE. Крайне не рекомендуется использовать эту расширенную форму для обычных проектов. Она в первую очередь нужна для внутренних особенностей описания настроек автосборки.

    В наивной идеальной картине мира каждый проект должен быть доступен через цепочку RECURSE от ya.make из корня репозитория, а пре- и посткомитные проверки выполняют инкрементальную сборку всей репозиторию способом, эквивалентным ya make -tt autocheck. Иногда при разработке библиотеки забывают добавить её в список RECURSE'ов родительской директории, но при этом разумеется добавляют PEERDIR зависимость на неё, там, где требуется. При этом сборка этой библиотеки в автосборке происходит, но её тесты в автосборке не собираются и не запускаются. Всегда добавляйте новые модули в список RECURSE'ов родительской директории.

    В реальности не все проекты собираются под все платформы, поэтому какие-то из путей могут быть достижимы из ya.make только в сборке под Linux, а какие-то только в сборке с использованием JDK15. Описание того, в какие платформы попадает сборка того или иного проекта, поддерживается централизованно в директории autocheck в корне репозитория.

    Этот макрос нельзя писать в модульном скоупе (между макросом начала модуля и макросом END()). Он пишется только в глобальном скоупе."

  34. Assistant

    "Добавляет проекты по указанным путям к списку стартовых целей сборки, если текущая директория уже находится в этом списке. Эти макросы не оказывают никакого эффекта, если текущий проект попал в сборку через PEERDIR, DEPENDS, или как инструмент сборки (через RUN_PROGRAM либо как часть реализации специфичного макроса, используемого в процессе сборки).

    При вызове ya make some/project/subdir another/project/dir, изначальный список стартовых проектов задается аргументами командной строки. В процессе чтения файлов ya.make, к стартовым целям будут добавляться директории, указанные через один из макросов RECURSE. Этот процесс продолжается рекурсивно.

    Простейшая и наиболее распространенная форма макроса RECURSE принимает в качестве аргументов список относительных путей и интерпретирует их как пути, относительно директории, содержащей текущий ya.make файл.

    Для подключения проектных тестов рекомендуется использовать форму RECURSE_FOR_TESTS, которая не добавляет указанные проекты в сборку, если сборка тестов не запрашивается. Как и в простой форме макроса, принимаемые пути интерпретируются как относительные пути относительно директории с текущим ya.make файлом.

    Если нужно задать путь за пределами текущей директории, используется форма RECURSE_ROOT_RELATIVE. Использование этой расширенной формы для обычных проектов крайне не рекомендуется; она в первую очередь нужна для внутренних настроек автосборки.

    В идеальном мире каждый проект должен быть доступен через цепочку RECURSE от корневого ya.make файла репозитория, а пре- и пост-коммитные проверки должны выполнять инкрементальную сборку всего репозитория эквивалентно команде ya make -tt autocheck. Иногда при разработке библиотеки её забывают добавить в список RECURSE родительской директории, но всё равно добавляют зависимость через PEERDIR там, где это требуется. В таком случае сборка этой библиотеки происходит, но её тесты не собираются и не запускаются в автосборке. Всегда добавляйте новые модули в список RECURSE в родительской директории.

    На практике не все проекты собираются для всех платформ, поэтому некоторые пути могут быть достижимы из ya.make только при сборке под Linux, а другие - только при сборке с использованием JDK15. Описание того, для каких платформ поддерживается сборка каждого проекта, хранится централизованно в директории autocheck в корне репозитория.

    Этот макрос нельзя использовать внутри модульного скоупа (между макросом начала модуля и макросом END()). Он пишется только в глобальном скоупе."

  35. User

    "### PEERDIR

    PEERDIR(Dirs..)
    

    Основной макрос указания зависимостей между модулями. Зависимости указываются ссылкой на директорию, в которой размещён файл bob.make c описанием сборки модуля, от которого данный модуль зависит.

    Чтобы PEERDIR был корректным, должна существовать директория, указанная в нём, в ней должен быть файл bob.make и этот файл должен описывать сборку модуля. Если что-то из этого не выполнено, то будет выдана ошибка конфигурации BadDir.

    Модуль, в котором написан PEERDIR, зависит от модуля, на который этот PEERDIR ссылается.

    PEERDIR интерпретируется с учётом типа модуля, в котором он указан. Он может обозначать один из двух вариантов зависимостей:

    1. Для программ и подобных им модулей PEERDIR означает включение или необходимость для сборки, т.е. модули в PEERDIR являются составными частями или требуются в построенном виде для построения данного. Например, библиотеки включаются в программы, а пакеты в go используют зависимые пакеты для собственной сборки.
    2. Для библиотек и подобных им модулей PEERDIR означает необходимость для использования, т.е. модули в PEERDIR не нужны для сборки данного, но нужны для использования. Например, когда библиотека в C++ зависит от другой, их можно собирать раздельно, но обе они должны быть влинкованы в программу, чтобы первую библиотеку можно было корректно использовать.

    Интерпретация PEERDIR зависимости определяет состав и порядок сборки:

    • Первый вариант требует построения всех зависимых модулей при сборке данного и до его сборки (результаты их сборки подаются на вход сборки данного).
    • Второй вариант не требует построения зависимых модулей при сборке данного, и они не будут строиться. Например, при сборке LIBRARY, библиотеки от которых она зависит, строиться не будут. При сборке программы PROGRAM все библиотеки будут строиться, но все они могут собираться параллельно без учёта зависимостей между ними.

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

    • Если LIBRARY зависит от PROTO_LIBRARY, то строить их как библиотеки можно параллельно, но в библиотеке будут доступны заголовочные файлы .pb.h, генерируемые в PROTO_LIBRARY.
    • Если в библиотеке LIBRARY указан макрос добавления путей в поиск ADDINCL(GLOBAL ...), то все зависящие от ней библиотеки тоже будут использовать этот путь для поиска include в своих файлах, хоть и строиться они будут независимо.

    PEERDIR — это всегда зависимость времени сборки, а не времени исполнения. Например, если из PY3TEST разрешён PEERDIR на PY3_PROGRAM это означает, что программа будет включена в сборку теста, а не будет доступна во время его исполнения. Для выражения зависимости времени исполнения теста используется макрос DEPENDS.

    Однако в определённых случаях зависимые модули могут расширять набор выходных артефактов (транзитивно) зависящего от них модуля. Так PACKAGE содержит, как часть своих результатов, копии программ, которые включены в него через PEERDIR."

  36. Assistant

    PEERDIR

    PEERDIR(Dirs..)
    

    Основной макрос для указания зависимостей между модулями. Директория, указанная в PEERDIR, должна содержать файл bob.make с описанием сборки модуля, от которого зависит данный модуль.

    Чтобы PEERDIR был корректным, необходимо выполнение следующих условий:

    1. Директория должна существовать.
    2. В этой директории должен быть файл bob.make.
    3. Файл bob.make должен описывать сборку модуля.

    Если хотя бы одно из этих условий не выполнено, будет выдана ошибка конфигурации BadDir.

    Модуль, в котором указан PEERDIR, зависит от модуля, на который ссылается этот PEERDIR.

    PEERDIR интерпретируется с учетом типа модуля, в котором он указан, и может обозначать один из двух вариантов зависимостей:

    1. Для программ и подобных им модулей PEERDIR означает включение или необходимость для сборки. То есть, модули в PEERDIR являются составными частями или необходимы в построенном виде для сборки данного модуля. Например, библиотеки включаются в программы, а пакеты в go требуют зависимых пакетов для своей сборки.
    2. Для библиотек и подобных им модулей PEERDIR означает необходимость для использования. То есть, модули в PEERDIR не нужны для сборки данного модуля, но необходимы для его использования. Например, библиотеки на C++ могут собираться раздельно, но обе они должны быть включены в программу для корректного использования первой библиотеки.

    Интерпретация зависимости PEERDIR задает состав и порядок сборки:

    • В первом варианте требуют построения всех зависимых модулей при сборке данного модуля и до его сборки (результаты их сборки используются при сборке данного).
    • Во втором варианте не требуется построение зависимых модулей при сборке данного, и они не будут собираться. Например, при сборке LIBRARY не будут строиться библиотеки, от которых она зависит. При сборке программы PROGRAM все библиотеки будут строиться, но могут собираться параллельно, без учета зависимостей между ними.

    С точки зрения свойств сборки, PEERDIR является зависимостью в любой интерпретации. Это означает, что от зависимого модуля к зависящему могут передаваться артефакты и свойства.

    • Если LIBRARY зависит от PROTO_LIBRARY, то их можно собирать параллельно, но в библиотеке будут доступны заголовочные файлы .pb.h, генерируемые в PROTO_LIBRARY.
    • Если в библиотеке LIBRARY указан макрос добавления путей в поиск ADDINCL(GLOBAL ...), то все зависящие от неё библиотеки тоже будут использовать этот путь для поиска include в своих файлах, даже если они строятся независимо.

    PEERDIR — это всегда зависимость времени сборки, а не времени исполнения. Например, если из PY3TEST разрешен PEERDIR на PY3_PROGRAM, это означает, что программа будет включена в сборку теста, а не будет доступна во время его исполнения. Для выражения зависимости времени исполнения теста используется макрос DEPENDS.

    Однако в определенных случаях зависимые модули могут расширять набор выходных артефактов (транзитивно) зависящего от них модуля. Например, PACKAGE содержит, как часть своих результатов, копии программ, включенных в него через PEERDIR.

  37. User

    "#### Ограничения

    Не любые PEERDIR допустимы. Зависимости между модулями могут быть ограничены как по естественным причинам (зависимость не имеет интерпретации), так и искусственно (явными правилами). Для PEERDIR есть следующий набор ограничений:

    • Промежуточные модули (вроде LIBRARY) не могут зависеть от финальных (вроде PROGRAM).
    • Сборочные модули (любые xPROGRAM, xLIBRARY, xTEST) не могут зависеть от агрегирующих модулей PACKAGE и UNION.
    • Никакие модули не могут зависеть от тестов*.
    • Модули размечены тэгами для контроля совместимости. Недопустимы PEERDIR между несовместимыми модулями, например PY2_LIBRARY не может зависеть от PY3_LIBRARY и наоборот. Поскольку программа на Python содержит интерпретатор фиксированной версии, то она целиком должна быть на одной версии Python: PY2_PROGRAM только на 2-й, PY3_PROGRAM только на 3-й. Через тэги также ограничены зависимости, не имеющие интерпретации в рамках системы сборки. Так система сборки просто не знала бы что делать с зависимостью LIBRARY от JAVA_LIBRARY.
    • Зависимости могут быть ограничены на основе их расположения автоматически для директорий internal и политиками. Такие ограничения описаны в [специальном разделе документации].

    Тестовые модули в Java могут зависеть друг от друга за счёт того, что в реальности такой модуль — это мультимодуль из собственно теста и java-библиотеки с кодом. Таким образом, в реальности эта зависимость превращается в зависимость одного теста от библиотеки с кодом другого. В частности, это означает, что при запуске зависящего теста зависимый запущен не будет."

  38. Assistant

    Ограничения

    Не все зависимости, указанные через PEERDIR, допустимы. Зависимости между модулями могут быть ограничены как по естественным причинам (зависимость не имеет интерпретации), так и искусственно (явными правилами). Для PEERDIR действуют следующие ограничения:

    • Промежуточные модули (например, LIBRARY) не могут зависеть от финальных модулей (например, PROGRAM).
    • Сборочные модули (любые xPROGRAM, xLIBRARY, xTEST) не могут зависеть от агрегирующих модулей, таких как PACKAGE и UNION.
    • Никакие модули не могут зависеть от тестов.
    • Модули размечены тегами для контроля совместимости. Недопустимы PEERDIR-зависимости между несовместимыми модулями. Например, PY2_LIBRARY не может зависеть от PY3_LIBRARY и наоборот. Поскольку программа на Python содержит интерпретатор фиксированной версии, она должна быть написана на одной версии Python: PY2_PROGRAM только на Python 2, PY3_PROGRAM только на Python 3. Через теги также ограничены зависимости, которые не могут быть интерпретированы в рамках системы сборки. Например, система сборки не смогла бы обработать зависимость LIBRARY от JAVA_LIBRARY.
    • Зависимости могут быть автоматически ограничены на основе их расположения, например, для директорий internal, или политиками. Такие ограничения описаны в [специальном разделе документации].

    Тестовые модули в Java могут зависеть друг от друга, поскольку на самом деле такие модули представляют собой мультимодули, включающие тест и java-библиотеку с кодом. Таким образом, в реальности эта зависимость превращается в зависимость одного теста от библиотеки с кодом другого теста. Это означает, что при запуске зависимого теста зависимый тест сам по себе не будет запущен.

  39. User

    "Система сборки bob make поддерживает мультимодули. По сути, это способ описать различное поведение сборки одного и того же исходного кода для разных вариантов использования. Собственно вариант использования в случае PEERDIR на мультимодуль определяется типом модуля, в котором этот PEERDIR написан.

    Примеры:

    • Для мультимодуля типа PROTO_LIBRARY, если PEERDIR написан в JAVA_LIBRARY, то получится зависимость на Java-вариант, а если из LIBRARY, то на C++-вариант.
    • PY23_LIBRARY — это мультимодуль, позволяющий собирать Python-код как в варианте для Python 3 (как PY3_LIBRARY), так и для Python 2 (как PY2_LIBRARY). Соответственно PEERDIR из PY3_PROGRAM выберет вариант для Python 3. Что важно, далее этот вариант для своих зависимостей будет делать такой же выбор (что в точности соответствует поведению PY3_LIBRARY).
    • PY3_PROGRAM является мультимодулем из библиотеки с кодом, аналогичной PY3_LIBRARY и собственно исполняемой программы, аналогичной PROGRAM со встроенным интерпретатором Python 3. Это позволяет иметь на неё PEERDIR из PY3TEST, который сделает код программы (библиотечную часть) доступным в коде теста.

    Выбором вариантов в мультимодулях управляют ровно те же тэги, которые используются для контроля совместимости. Т.е., по сути, общее правило такое:

    PEERDIR разрешён только на совместимый модуль, если вариантов несколько совместимый будет выбран из них, если варианта нет совсем или нет совместимого, то будет выдана ошибка конфигурации BadDir."

  40. Assistant

    Система сборки bob make поддерживает мультимодули. Это способ описания различных вариантов сборки одного и того же исходного кода для разных целей использования. В случае использования PEERDIR на мультимодуль, конкретный вариант определяется типом модуля, в котором этот PEERDIR указан.

    Примеры:

    • Для мультимодуля типа PROTO_LIBRARY, если PEERDIR указан в JAVA_LIBRARY, то создается зависимость на Java-вариант, а если в LIBRARY, то на C++-вариант.
    • PY23_LIBRARY — это мультимодуль, позволяющий собирать Python-код для Python 3 (как PY3_LIBRARY) и Python 2 (как PY2_LIBRARY). Соответственно, PEERDIR из PY3_PROGRAM выберет вариант для Python 3. Важно отметить, что этот вариант для своих зависимостей также будет выбирать соответствующие варианты (это соответствует поведению PY3_LIBRARY).
    • PY3_PROGRAM является мультимодулем, включающим библиотеку с кодом, аналогичным PY3_LIBRARY, и исполняемую программу, аналогичную PROGRAM, но со встроенным интерпретатором Python 3. Это позволяет использовать PEERDIR из PY3TEST, который сделает код программы (ее библиотечную часть) доступным в коде теста.

    Выбор вариантов в мультимодулях управляется теми же тегами, которые используются для контроля совместимости. Общее правило такое:

    PEERDIR разрешен только на совместимый модуль. Если вариантов несколько, будет выбран совместимый. Если вариантов нет вообще или нет совместимых, будет выдана ошибка конфигурации BadDir.

  41. User

    "Добавляет в сборку один файл исходного кода.

    Файл будет обработан на основе его расширения. К стандартной обработке будут добавлены флаги Flags... специфичные для команды обработки этого типа файлов (напр. флаги компиляции для С++)."

  42. Assistant

    "Добавляет один файл исходного кода в сборку.

    Файл будет обработан на основе его расширения. При стандартной обработке будут также применены флаги Flags..., специфичные для команды обработки этого типа файлов (например, флаги компиляции для C++)."

  43. User

    "Добавляет в сборку набор файлов исходного кода. Файл будет обработан на основе его расширения.

    Кроме того, что макрос SRCS работает по-разному для разных файлов, перечисленных в них, он также работает по-разному в зависимости от модуля, в котором написан и даже в зависимости от варианта мультимодуля, который выбран.

    • Макрос SRCS в модулях GO_LIBRARY, GO_PROGRAM и т.п. поддерживает исходный код на языке go, а модули на других языках их не поддерживают.
    • в PROTO_LIBRARY файлы .proto обрабатываются по-разному для разных языковых вариантов.

    Параметр GLOBAL позволяет гарантировать включение результат сборки файла в программу, как если бы объектный файл, полученный от сборки указанного исходного файла, подавался бы в строку линковки непосредственно. Он действует только на один файл, указанный сразу после него. Макрос GLOBAL_SRCS эквивалентен указанию GLOBAL в макросе SRCS перед всеми перечисленными файлами.

    Для сборки кода на Python и Java исходные файлы указываются в макросах PY_SRCS и JAVA_SRCS соответственно. Это связано с тем, что исходные файлы при сборке для этих языков обрабатываются специальным образом и макросы позволяют указывать специальные параметры для этой обработки.

    При этом:

    • Модули Python поддерживают макрос SRCS для исходного кода на С++ и других поддержанных в макросе языках. Использование этого макроса вызовет обработку файлов до объектного кода и складывание этого кода в библиотеку. Код будет влинкован в программу и может быть использован из кода на Python через биндинги, например через Cython.
    • Модуль EXTERNAL_JAVA_LIBRARY поддерживает очень ограниченный набор типов файлов в макросе SRCS через специальную обработку файлов, совместимую с Java (порождение .java или .jsrc на выходе)."
  44. Assistant

    "Добавляет набор файлов исходного кода в сборку, обрабатывая каждый файл на основе его расширения.

    Макрос SRCS действует по-разному для различных типов файлов и модулей, а иногда и для разных вариаций мультимодуля:

    • В модулях типа GO_LIBRARY, GO_PROGRAM и т.п. макрос SRCS поддерживает исходный код на языке Go, в то время как модули на других языках его не поддерживают.
    • В PROTO_LIBRARY файлы .proto обрабатываются по-разному в зависимости от языкового варианта.

    Параметр GLOBAL обеспечивает включение результата сборки файла в программу, как если бы объектный файл, полученный из указанного исходного файла, подавался в строку линковки напрямую. Параметр действует только на один файл, указанный сразу после него.

    Макрос GLOBAL_SRCS эквивалентен применению параметра GLOBAL в макросе SRCS перед всеми перечисленными файлами.

    Для сборки кода на Python и Java исходные файлы указываются в макросах PY_SRCS и JAVA_SRCS соответственно. Это связано с тем, что при сборке для этих языков исходные файлы обрабатываются специальным образом, и эти макросы позволяют указывать специальные параметры для этой обработки.

    Дополнительно:

    • Модули Python поддерживают макрос SRCS для исходного кода на C++ и других поддерживаемых в этом макросе языках. Использование этого макроса приведет к обработке файлов до объектного кода, который будет собран в библиотеку. Этот код затем будет линкован в программу и может быть использован из Python-кода через биндинги, такие как Cython.
    • Модуль EXTERNAL_JAVA_LIBRARY поддерживает очень ограниченный набор типов файлов в макросе SRCS через специальную обработку файлов, совместимую с Java (например, порождение .java или .jsrc на выходе)."
  45. User

    "Макрос SRCDIR позволяет добавить пути для поиска исходных файлов (входов для команд). Относительного этого пути будут искаться не только исходные файлы в макросе SRCS и подобных, он будет действовать на поиск входных файлов во всех макросах, например в параметре <value> макроса RESOURCE или в параметре IN макроса RUN_PROGRAM.

    При описании сборки в bob.make входные файлы могут быть указаны полностью, даже с указанием ${BUILD_ROOT} (дерево исходного кода) или ${DIR_BUILD_ROOT} (дерево генерированных файлов). Однако в большинстве случаев указывается относительный путь, который система сборки должна превратить в путь до реального файла или в дереве исходного кода, или в дереве генерированных файлов. Этот процесс называется резолвинг. Он пытается подобрать директорию относительно которой указано имя файла. По умолчанию список директорий для такого поиска — это ${BUILD_ROOT} (дерево исходного кода), ${DIR_BUILD_ROOT} (дерево генерированных файлов), ${CURDIR} (директория проекта в дереве исходного кода). Именно в таком порядке.

    Макрос SRCDIR позволяет добавить к списку другие директории.

    • Директории в дереве исходного кода должны указываться от корня Аркадии, указание ${BUILD_ROOT} не обязательно.
    • Директории в дереве генерированных файлов (если хочется указывать генерированные файлы не от корня) должны быть обязательно указаны от корня с указанием самого корня, т.е. ${DIR_BUILD_ROOT}/1st_level_dir/subdir
    1. Мы не рекомендуем использовать макрос SRCDIR без необходимости: в большинстве случаев он осложняет понимание описания сборки поскольку скрывает реально размещение исходных файлов из макросов.
    2. Не используйте макрос SRCDIR чтобы использовать один и те же исходные файлы в разных модулях. Каждый файл анализируется системой сборки один раз и воровство исходных файлов может приводить к потерянным зависимостям, неоднозначностям описания сборки и другим проблемам."
  46. Assistant

    Макрос SRCDIR позволяет добавлять пути для поиска исходных файлов (входов для команд). Относительно этих путей будут искаться не только файлы, указанные в макросе SRCS и аналогичных макросах, но и входные файлы во всех остальных макросах, например в параметре <value> макроса RESOURCE или в параметре IN макроса RUN_PROGRAM.

    При описании сборки в bob.make входные файлы могут быть указаны полностью, даже с указанием ${BUILD_ROOT} (дерево исходного кода) или ${DIR_BUILD_ROOT} (дерево сгенерированных файлов). Однако, в большинстве случаев, указывается относительный путь, который система сборки должна превратить в путь к реальному файлу либо в дерево исходного кода, либо в дерево сгенерированных файлов. Этот процесс называется резолвинг. Он пытается подобрать директорию, относительно которой указано имя файла. По умолчанию, список директорий для такого поиска включает ${BUILD_ROOT} (дерево исходного кода), ${DIR_BUILD_ROOT} (дерево сгенерированных файлов) и ${CURDIR} (директория проекта в дереве исходного кода) — именно в таком порядке.

    Макрос SRCDIR позволяет расширить этот список, добавляя другие директории.

    • Директории в дереве исходного кода должны указываться от корня Аркадии, указание ${BUILD_ROOT} не обязательно.
    • Директории в дереве сгенерированных файлов (если требуется указание генерированных файлов не от корня) должны быть обязательно указаны от корня с включением самого корня, например ${DIR_BUILD_ROOT}/1st_level_dir/subdir.

    Рекомендации по использованию макроса SRCDIR:

    1. Мы не рекомендуем использовать макрос SRCDIR без необходимости: в большинстве случаев он усложняет понимание описания сборки, так как скрывает реальное расположение исходных файлов в макросах.
    2. Не используйте макрос SRCDIR, чтобы переиспользовать одни и те же исходные файлы в разных модулях. Каждый файл анализируется системой сборки один раз, и такое воровство исходных файлов может привести к пропущенным зависимостям, неоднозначностям в описании сборки и другим проблемам.
  47. User

    "Добавление путей поиска файлов для include/import конструкций в файлах, участвующих в сборке модуля.

    Система сборки анализирует исходные файлы, чтобы найти зависимости между файлами. Она получает список имён, по которому ей надо найти реальные файлы. Этот процесс называется резолвинг. Он пытается подобрать директорию относительно которой указано имя файла. При этом для инклудов и импортов этот процесс отличается от такого же для исходных файлов:

    • Поиск может быть разным для разных типов файлов.
    • Часть файлов может вообще отсутствовать в Аркадии (например, загружаться вместе со сборочными инструментами). С другой стороны, может иметься в виду несколько разных файлов. Что делать в таком случае написано в разделе об инклудах в С++.
    • По умолчанию список директорий для такого поиска — это . (путь до файла, в котором написан include, применяется не всегда), ${DIR_BUILD_ROOT} (дерево генерированных файлов), ${BUILD_ROOT} (дерево исходного кода). Сравните этот список с аналогичным в описании SRCDIR.

    Кроме резолвинга ADDINCL передаёт пути поиска в соответствующие инструменты, чтобы при исполнении сборки уже сами инструменты могли найти упомянутые файлы.

    Макрос ADDINCL позволяет задавать директории поиска для каждого языка независимо. Так как самый большой потребитель данного макроса это C++, то при использовании без указания языка директории считается директорией поиска для C++. Помимо этого, можно управлять путями поиска включаемых файлов для следующих языков:

    • ADDINCL(FOR asm ...)
    • ADDINCL(FOR asp ...)
    • ADDINCL(FOR c ...) дефолт если не указан язык явно
    • ADDINCL(FOR cython ...)
    • ADDINCL(FOR flatc ...)
    • ADDINCL(FOR fortran ...)
    • ADDINCL(FOR gperf ...)
    • ADDINCL(FOR idl ...)
    • ADDINCL(FOR lex ...)
    • ADDINCL(FOR nlg ...)
    • ADDINCL(FOR proto ...)
    • ADDINCL(FOR ragel ...)
    • ADDINCL(FOR sc ...)
    • ADDINCL(FOR swig ...)
    • ADDINCL(FOR xs ...)
    • ADDINCL(FOR xsyn ...)
    • ADDINCL(FOR bobcc ...)
    • ADDINCL(FOR ydl ...)

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

    • GLOBAL действует на все модули, зависящие от данного как напрямую, так и транзитивно через другие модули. Это позволяет использовать имя файла относительно такого пути поиска как в исходных, так и в заголовочных файлах, распространяя их использование по зависимостям.
    • ONE_LEVEL действует только на модули, зависящие от данного напрямую. Для такого поведения есть два сценария:
      1. Путь поиска для приватного интерфейса, который должен использоваться только другими частями реализации библиотеки, но не должен быть доступен внешним пользователям.
      2. Путь поиска обеспечивает резолвинг локальных файлов с распространёнными именами (например, stdio.h или config.h). В норме такие имена должны ссылаться или на стандартную библиотеку или на файл той библиотеки, к которой относится код. ADDINCL(GLOBAL) привёл бы к нежелательному резолвингу в зависящих модулях, а писать ADDINCL() во всех прямых пользователях может быть неудобно и тяжело в поддержке.

    В макросе ADDINCL:

    • Директории в дереве исходного кода должны указываться от корня репозитория проекта, указание ${BUILD_ROOT} не обязательно.
    • Директории в дереве генерированных файлов (если хочется указывать генерированные файлы не от корня) должны быть обязательно указаны от корня с указанием самого корня, т.е. ${DIR_BUILD_ROOT}/1st_level_dir/subdir

    Рекомендуется все импорты и инклуды делать только от корня репозитория проекта, механизм ADDINCL предназначен для работы с contrib кодом либо кодом, который выкладывается в opensource."

  48. Assistant

    Макрос ADDINCL позволяет добавить пути для поиска файлов, используемых в конструкциях include/import в файлах, участвующих в сборке модуля.

    Система сборки анализирует исходные файлы для выявления зависимостей между ними. Она получает список имен, по которым ей нужно найти реальные файлы. Этот процесс называется резолвинг. Процесс резолвинга пытается определить директорию, относительно которой указано имя файла. Для include и import операций этот процесс отличается от резолвинга исходных файлов:

    • Поиск может быть разным для различных типов файлов.
    • Часть файлов может отсутствовать в Аркадии (например, загружаться вместе со сборочными инструментами). В некоторых случаях это может означать несколько разных файлов. Дополнительная информация об этом указана в разделе о инклуд-операциях в С++.
    • По умолчанию список директорий для поиска включает в себя . (путь до файла, в котором написан include, применяется не всегда), ${DIR_BUILD_ROOT} (дерево генерированных файлов), ${BUILD_ROOT} (дерево исходного кода). Это отличается от списка, используемого в SRCDIR.

    Помимо резолвинга, макрос ADDINCL передает пути для поиска в соответствующие инструменты, чтобы при сборке эти инструменты могли найти упомянутые файлы.

    Макрос ADDINCL позволяет задавать директории поиска для каждого языка независимо. Так как основной потребитель этого макроса — C++, то при использовании без указания языка директории считаются директорией поиска для C++. Также можно указать пути для других языков:

    • ADDINCL(FOR asm ...)
    • ADDINCL(FOR asp ...)
    • ADDINCL(FOR c ...) — используется по умолчанию, если язык не указан явно
    • ADDINCL(FOR cython ...)
    • ADDINCL(FOR flatc ...)
    • ADDINCL(FOR fortran ...)
    • ADDINCL(FOR gperf ...)
    • ADDINCL(FOR idl ...)
    • ADDINCL(FOR lex ...)
    • ADDINCL(FOR nlg ...)
    • ADDINCL(FOR proto ...)
    • ADDINCL(FOR ragel ...)
    • ADDINCL(FOR sc ...)
    • ADDINCL(FOR swig ...)
    • ADDINCL(FOR xs ...)
    • ADDINCL(FOR xsyn ...)
    • ADDINCL(FOR bobcc ...)
    • ADDINCL(FOR ydl ...)

    Макрос ADDINCL позволяет указать директории поиска включаемых файлов не только для текущего модуля, но и для модулей, которые от него зависят, с помощью модификаторов GLOBAL или ONE_LEVEL. Это особенно важно, когда одна сторонняя библиотека в своих заголовочных файлах включает заголовочные файлы другой сторонней библиотеки. В этом случае дополнительные флаги с директориями поиска нужно передавать при компиляции как самой библиотеки, так и тех библиотек, которые её используют.

    • GLOBAL действует на все модули, зависящие от данного как напрямую, так и транзитивно через другие модули. Это позволяет использовать имя файла относительно указанного пути поиска как в исходных, так и в заголовочных файлах, распространяя их использование по зависимостям.
    • ONE_LEVEL действует только на модули, напрямую зависящие от данного. Такое поведение может применяться в двух сценариях:
      1. Путь поиска для приватного интерфейса, который должен использоваться только другими частями реализации библиотеки, но не должен быть доступен внешним пользователям.
      2. Путь поиска обеспечивает резолвинг локальных файлов с общими именами (например, stdio.h или config.h). Обычно такие имена должны ссылаться на стандартную библиотеку или на файл той библиотеки, к которой относится код. Использование ADDINCL(GLOBAL) привело бы к нежелательному резолвингу в зависящих модулях, и добавление ADDINCL() во всех прямых пользователях может быть неудобным и сложным в поддержке.

    При использовании макроса ADDINCL:

    • Директории в дереве исходного кода должны указываться от корня репозитория проекта, указание ${BUILD_ROOT} не обязательно.
    • Директории в дереве сгенерированных файлов (если требуется указание генерированных файлов не от корня) должны быть указаны от корня с указанием самого корня, например ${DIR_BUILD_ROOT}/1st_level_dir/subdir.

    Рекомендуется указывать все импорты и инклуды от корня репозитория проекта. Механизм ADDINCL предназначен для работы с contrib кодом или кодом, который выкладывается в opensource.

  49. User

    " Макросы для запуска производной кодогенерации с помощью, программы, собранной из репозитория (RUN_PROGRAM) или скрипта на Python (2-й или 3-й версии) или Lua. Основные принципы работы и значение параметров совпадают для всех макросов и будут описаны ниже, отличается только первый параметр.

    • В RUN_PROGRAM первым параметром указывается путь до директории с bob.make, описывающем сборку программы (PROGRAM, GO_PROGRAM, PY3_PROGRAM и т.п.). В процессе сборки эта программа будет собрана под сборочную платформу(release) и исполнена для генерации исходного кода. При этом все зависимости программы будут автоматически учтены и при их изменении программа будет перестроена и перезапущена.
    • В остальных макросах первым параметром указывается путь до файла скрипта от корня репозитория. Как в случае Lua, так и в случае Python скрипт не будет компилировать и будет исполняться интерпретатором. Если скрипт зависит от других фалов их надо будет явно указать в параметре IN иначе они не будут учтены.

    Следующие параметры общие для всех макросов.

    • args - Аргументы программы или макроса. Будут переданы в командной строке. Если аргументы соответствуют именам, указанным в IN, IN_NOPARSE, TOOL, OUT или OUT_NOAUTO, то аргументы будут превращены в абсолютные пути, соответствующие файлам в этих параметрах. Считается, что они в точности являются входными или выходными файлами, указанными в параметрах. На данный момент не существует способа отключить это поведение. Если оно не желательно, рекомендуется каким-то образом изменить имя в параметре (например, добавить символ в конце) и затем обработать эту ситуацию в программе/скрипте либо добавить параметр, соответствующий корню Аркадии в исходном или сборочном дереве и на основе него рассчитать относительный путь.

    • CWD - Директория, к которой надо запускать программу/скрипт. Путь надо указывать вместе с корнем вроде ${BUILD_ROOT}, ${BINDIR} и т.п. На данный момент у этого параметра нет фиксированного умолчания (локально и в distbuild оно разное), поэтому если рабочая директория важна, указывайте её явно.

    • ENV - Переменные среды для запуска программы/скрипта. Если программе/скрипту нужны переменные среды - указывайте их явно. Наличие переменных $HOME, $PATH и подобных в среде исполнения программы/скрипта не гарантируется.

    • TOOL - Пути до bob.make собирающих программы, динамические библиотеки и т.п. нужные вовремя исполнения программы или скрипта. Все они будут собраны под сборочную платформу и доступны по своим путям в Аркадии от ${DIR_BUILD_ROOT} во время исполнения программы/скрипта.

    • IN[_NOPARSE] - входные файлы для запуска программы/макроса. Могут быть как явными, так и неявными. Явные должны быть указаны в Args, значения из IN и IN_NOPARSE сами по себе в командную строку не попадают, но засчитываются как зависимости для запуска программы/скрпипта.

      • Значения параметров IN и IN_NOPARSE отображаются на реальные файлы (резолвятся) по правилам для входных файлов.
      • Обязательно указывайте все файлы, используемые генератором (явно или неявно) в этом параметре. Иначе, при изменении неуказанного файла не случится перегенерация.
      • Файлы из параметра IN анализируются на наличие зависимостей на основе их расширений если расширение поддержано в анализе (парсинге). Чтобы отключить это поведение для файлов, у которых оно по расширению включено, используйте параметр IN_NOPARSE, перечисленные в нём файлы интерпретируются как простой текст и не анализируются. Параметр требует перечислять именно файлы, не директории. Однако, с помощью макроса DECLARE_IN_DIRS можно сформировать список файлов в директории по маске в виде переменной. Эту переменную можно передать в параметр IN, а также получить через нее имена для передачи в командную строку.
    • OUT[_NOAUTO] - выходные файлы, порождаемые генератором. Если путь не указан явно с ${DIR_BUILD_ROOT}, то он считается относительным от ${BINDIR}.

      • Все генерируемые файлы должны быть выписаны явно. Без этого знания система сборки не сможет встроить результаты в дальнейшую обработку. Если результатов много, можно запаковать их генератором в .tar-архив и обрабатывать в следующих командах уже весь архив целиком, описав его там как вход.
      • Файлы из параметра OUT далее автоматически обрабатываются в соответствии с их расширением. Чтобы отключить эту обработку или если правил обработки нет, используйте вариант OUT_NOAUTO.
    • STDOUT[_NOAUTO] - параметр, аналогичный OUT, но для случая, когда генератор пишет в стандартный поток вывода (stdout). Система сборки сама запишет вывод в файл с заданным именем.

      • По понятным причинам может быть указан только один файл как STDOUT или STDOUT_NOAUTO.
    • OUTPUT_INCLUDES - параметр, позволяющий задать зависимости генерируемых файлов. Для исходных файлов система сборки выводит зависимости анализом файла по расширению. Поскольку граф зависимостей строится до исполнения сборки, то генерируемые файлы так обработать не выйдет. В этом случае зависимости надо указывать явно. OUTPUT_INCLUDES позволяет перечислить файлы, от которых зависят результаты генерации. Эти файлы будут предоставлены командам обработки генерируемых файлов, а не команде генерации. При их изменении будет перезапущена обработка результатов генерации (например, компиляция), а не сама генерация.

      • Все файлы, перечисленные в этом параметре, являются зависимостями всех файлов, описанных в OUT[_NOAUTO] и [STDOUT[_NOAUTO]. Не предусмотрено более тонкой фильтрации ни по именам выходов ни по расширениям.
      • Для определённых расширений система сборки считает файлы зависимостями не только самих результатов генерации, но зависимостями результатов обработки файлов генерации (например, при генерации .pyx это будут и другие .pyx и .h в .pyx). Здесь также не предусмотрено фильтрации.
      • Не указывайте в этом параметре значения из параметров OUT[_NOAUTO] и [STDOUT[_NOAUTO] — это создаст цикл по зависимостям файла от самого себя и может привести к проблемам в анализе зависимостей таких файлов.

      Если программа-генератор, используемая в RUN_PROGRAM всегда генерирует одинаковые зависимости (или часть зависимостей), то она может описать их в своём модуле макросом INDUCED_DEPS, в этом случае их не надо будет перечислять в OUTPUT_INCLUDES всех RUN_PROGRAM этого генератора.

    • INDUCED_DEPS - параметр, позволяющий задать зависимости генерируемых файлов определенного типа. В некоторых случаях параметр OUTPUT_INCLUDES действует слишком неизбирательно, назначая перечисленные файлы завсисимостями всем результатам макроса. В тех случаях, когда важно чтобы файлы стали зависимостями только определенных типов файлов можно воспользоваться этим параметром. В него надо передавать значение переменной, подготовленное макросом PREPARE_INDUCED_DEPS.

    • Все списочные параметры такие как ENV, IN, OUT и т.п. могут встречаться в вызове макроса несколько раз. Значением параметра является список строк, разделённых по пробелам от имени параметра до имени другого параметра или закрывающей скобки.

      Например для a/b/bob.make:

      RUN_PYTHON3(run.py x.inp xx.inp y.cpp ENV X=xx IN x.inp xx.inp OUT y.cpp IN .run.settings ENV HOME=${CURDIR})
      
      # Командная строка:
      #   python3 ${BUILD_ROOT}/a/b/run.py ${BUILD_ROOT}/a/b/x.inp ${BUILD_ROOT}/a/b/xx.inp ${DIR_BUILD_ROOT}/a/b/y.cpp
      # Параметры:
      #   ENV=['X=xx', 'HOME=${BUILD_ROOT}/a/b']
      #   IN=['${BUILD_ROOT}/a/b/x.inp', '${BUILD_ROOT}/a/b/xx.inp', '${BUILD_ROOT}/a/b/.run.settings']
      #   OUT=['${DIR_BUILD_ROOT}/a/b/y.cpp']
      

    Параметры OUT_NOAUTO или STDOUT_NOAUTO одного макроса могут присутствовать в IN, IN_NOPARSE и OUTPUT_INCLUDES другого. При чём они могут быть написаны как в одном bob.make, так и в разных. Важно чтобы bob.make с макросом-потребителем имел PEERDIR зависимость (хотя бы транзитивную) на bob.make c макросом-источником."

  50. Assistant

    Макросы для запуска производной кодогенерации с помощью программ, собранных из репозитория (RUN_PROGRAM), или скриптов на Python (2-й или 3-й версии) или Lua. Основные принципы работы и значение параметров одинаковы для всех макросов и будут описаны ниже, отличается только первый параметр.

    • В RUN_PROGRAM первым параметром указывается путь до директории с bob.make, описывающим сборку программы (PROGRAM, GO_PROGRAM, PY3_PROGRAM и т.п.). В процессе сборки эта программа будет собрана под сборочную платформу (release) и выполнена для генерации исходного кода. Все зависимости программы будут автоматически учтены, и при их изменении программа будет перестроена и перезапущена.
    • В остальных макросах первым параметром указывается путь до файла скрипта от корня репозитория. В случае Lua или Python скрипт не будет компилироваться и будет выполняться интерпретатором. Если скрипт зависит от других файлов, их нужно явно указать в параметре IN, иначе они не будут учтены.

    Следующие параметры общие для всех макросов:

    • args - Аргументы программы или скрипта, передаваемые в командной строке. Если аргументы соответствуют именам, указанным в IN, IN_NOPARSE, TOOL, OUT или OUT_NOAUTO, то они будут превращены в абсолютные пути к соответствующим файлам. Если это поведение нежелательно, рекомендуется добавить символ в имени параметра или обработать его в программе или скрипте.

    • CWD - Директория, из которой нужно запускать программу или скрипт. Указывайте путь вместе с корнями, такими как ${BUILD_ROOT}, ${BINDIR} и т.п. По умолчанию, значение этого параметра может различаться локально и в distbuild, поэтому, если рабочая директория важна, указывайте её явно.

    • ENV - Переменные среды для запуска программы или скрипта. Указывайте их явно, если они необходимы, поскольку наличие переменных $HOME, $PATH и подобных не гарантируется.

    • TOOL - Пути до bob.make, в которых собираются программы, динамические библиотеки и т.п., нужные во время выполнения программы или скрипта. Все они будут собраны под сборочную платформу и доступны по своим путям в Аркадии из ${DIR_BUILD_ROOT} во время выполнения программы или скрипта.

    • IN[_NOPARSE] - Входные файлы для запуска программы или скрипта. Их можно указывать явно или неявно. Явные файлы должны быть указаны в args. Значения из IN и IN_NOPARSE сами по себе в командную строку не попадают, но считаются зависимостями для запуска программы или скрипта.

      • Файлы из параметров IN и IN_NOPARSE резолвятся на реальные файлы.
      • Обязательно указывайте все файлы, используемые генератором (явно или неявно), иначе при изменении неуказанного файла перегенерация не произойдёт.
      • Файлы из IN анализируются на наличие зависимостей на основе их расширений, если это поддерживается. Чтобы отключить это поведение для некоторых файлов, используйте IN_NOPARSE, тогда файлы будут трактоваться как простой текст и не анализироваться.
      • Параметр требует перечислять именно файлы, а не директории. С помощью макроса DECLARE_IN_DIRS можно сформировать список файлов в директории по маске в виде переменной и передать её в параметр IN.
    • OUT[_NOAUTO] - Выходные файлы, создаваемые генератором. Если путь не указан явно с ${DIR_BUILD_ROOT}, он считается относительным от ${BINDIR}.

      • Все генерируемые файлы должны быть явно описаны. Иначе система сборки не сможет встроить результаты в дальнейшую обработку. Если файлов много, можно упаковать их в tar-архив и обрабатывать далее этот архив, описав его как вход.
      • Файлы из OUT далее автоматически обрабатываются в соответствии с их расширениями. Чтобы отключить эту обработку или если правило обработки нет, используйте OUT_NOAUTO.
    • STDOUT[_NOAUTO] - Параметр, аналогичный OUT, для случая, когда генератор пишет в стандартный поток вывода (stdout). Система сборки сама запишет вывод в файл с заданным именем.

      • По понятным причинам можно указать только один файл в STDOUT или STDOUT_NOAUTO.
    • OUTPUT_INCLUDES - Параметр, позволяющий задать зависимости генерируемых файлов. Для исходных файлов система сборки выводит зависимости анализом файла по расширению. Поскольку граф зависимостей строится до выполнения сборки, генерируемые файлы нужно указывать явно.

      • Все файлы, перечисленные в этом параметре, являются зависимостями всех файлов из OUT[_NOAUTO] и STDOUT[_NOAUTO]. Более тонкой фильтрации по именам или расширениям нет.
      • Для некоторых расширений система сборки считает файлы зависимостями не только результатов генерации, но и зависимостями результатов обработки этих файлов (например, .pyx файлы). Здесь тоже нет фильтрации.
      • Не указывайте здесь значения из OUT[_NOAUTO] и STDOUT[_NOAUTO], чтобы избежать циклов зависимостей.

      Если программа-генератор всегда генерирует одни и те же зависимости (или их часть), она может описать их в своем модуле с помощью макроса INDUCED_DEPS. В этом случае их не нужно перечислять в OUTPUT_INCLUDES для всех RUN_PROGRAM этого генератора.

    • INDUCED_DEPS - Параметр для указания зависимостей генерируемых файлов определенного типа. В некоторых случаях параметр OUTPUT_INCLUDES назначает слишком общие зависимости. Если важно, чтобы файлы стали зависимостями только определенных типов файлов, используйте этот параметр. Его значение должно быть подготовлено с помощью макроса PREPARE_INDUCED_DEPS.

    • Все списочные параметры, такие как ENV, IN, OUT и т.п., могут встречаться в макросе несколько раз. Значением параметра является список строк, разделенных пробелами от имени параметра до имени другого параметра или до закрывающей скобки.

      Пример для a/b/bob.make:

      RUN_PYTHON3(run.py x.inp xx.inp y.cpp ENV X=xx IN x.inp xx.inp OUT y.cpp IN .run.settings ENV HOME=${CURDIR})
      
      # Командная строка:
      #   python3 ${BUILD_ROOT}/a/b/run.py ${BUILD_ROOT}/a/b/x.inp ${BUILD_ROOT}/a/b/xx.inp ${DIR_BUILD_ROOT}/a/b/y.cpp
      # Параметры:
      #   ENV=['X=xx', 'HOME=${BUILD_ROOT}/a/b']
      #   IN=['${BUILD_ROOT}/a/b/x.inp', '${BUILD_ROOT}/a/b/xx.inp', '${BUILD_ROOT}/a/b/.run.settings']
      #   OUT=['${DIR_BUILD_ROOT}/a/b/y.cpp']
      

    Параметры OUT_NOAUTO или STDOUT_NOAUTO из одного макроса могут присутствовать как IN, IN_NOPARSE и OUTPUT_INCLUDES в другом макросе. Они могут быть указаны как в одном bob.make, так и в разных. Важно, чтобы bob.make с макросом-потребителем имел зависимость PEERDIR (хотя бы транзитивную) на bob.make с макросом-источником.