Ты технический писатель. Перефразируй "В отличии от большинства других макросов…
- User
Ты технический писатель. Перефразируй "В отличии от большинства других макросов bob.make, относительный порядок базовых управляющих конструкций имеет значение. IF видит то значение переменной, которое было выставлено раньше в bob.make, и не видит то, которое будет выставлено ниже по тексту. Однако, если установка переменной меняет свойства модуля или его команд, она может повилять и на конструкции, написанные выше по тексту"
- Assistant
В отличие от большинства других макросов в bob.make, относительная последовательность базовых управляющих конструкций имеет значение. Команда IF интерпретирует текущее значение переменной, установленное выше по тексту, и не видит будущие изменения, расположенные ниже. Однако, если установка переменной влияет на свойства модуля или его команд, это может отразиться и на уже написанных выше конструкциях.
- 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}/ как принадлежность к дереву исходных файлов. "
- 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}/ как принадлежность к дереву исходных файлов.
- User
Перефразируй "Тестовые включения могут приводить к тому, что один и тот же файл будет по разным путям от основного bob.make включен несколько раз. Это будет приводить к замедлению работы а также, возможно, к дублированию значений при вызове макроса SET_APPEND.
Чтобы избежать этого рекомендуется использовать макрос INCLUDE_ONCE(). Файл, в котором написан такой макрос будет обработан только один раз для каждого bob.make-файла. Остальные его включения при обработке этого bob.make будут проигнорированы.
Макрос без параметров или с параметром yes включает однократную обработку файла. Макрос с параметром no выключает однократную обработку файла. Это может быть полезно чтобы зафиксировать явно, что файл предназначен для многократного включения. И особенно это будет полезно при смене поведения INCLUDE по-умолчанию."
- Assistant
Повторные включения могут вызвать ситуацию, когда один и тот же файл будет включён несколько раз через различные пути от основного bob.make, что приведёт к замедлению работы и потенциальному дублированию значений при использовании макроса SET_APPEND.
Для предотвращения этого рекомендуется применять макрос INCLUDE_ONCE(). Файл, содержащий этот макрос, будет обрабатываться только один раз для каждого bob.make-файла. Все последующие включения этого файла в рамках обработки текущего bob.make будут игнорироваться.
Макрос INCLUDE_ONCE без параметров или с параметром yes активирует однократную обработку файла. Макрос INCLUDE_ONCE с параметром no отключает однократную обработку файла. Это может быть полезно для явного обозначения того, что файл предназначен для многократного включения, особенно если поведение INCLUDE по умолчанию изменится.
- User
"Где бы макрос INCLUDE_ONCE не исполнился в файле, этот файл не будет интерпретирован второй раз. Однако рекомендуется писать макрос в самом начале файла и настоятельно не рекомендуется ставить его под IF."
- Assistant
Независимо от того, где в файле выполнен макрос INCLUDE_ONCE, этот файл не будет интерпретирован повторно. Однако рекомендуется размещать этот макрос в самом начале файла и настоятельно не рекомендуется вставлять его внутри условных конструкций (IF).
- User
"Задаёт или изменяет значение переменной, перетирая то значение, которое возможно было выставлено раньше.
SET_APPEND"
- Assistant
"Задает или изменяет значение переменной, перезаписывая любое ранее установленное значение.
SET_APPEND"
- User
"Добавляет значение к переменной. Существующее значение могло быть определено в глобальной конфигурации сборки, например
SET_APPEND(CFLAGS -fno-omit-frame-pointer)добавит к глобально определённым для C++ и C модулей флагам тот, что требуется текущему модулю." - Assistant
"Добавляет значение к переменной. Существующее значение могло быть установлено в глобальной конфигурации сборки. Например, команда
SET_APPEND(CFLAGS -fno-omit-frame-pointer)добавит указанный флаг к глобально определённым флагам для модулей C++ и C, обеспечивая требуемый флаг для текущего модуля." - User
"Задаёт значение по умолчанию для переменной. В отличие от
SET(VarName VarValue)установит запрошенное значение переменной только если для данной переменной значение ещё нигде не было определено." - Assistant
"Задает значение по умолчанию для переменной. В отличие от
SET(VarName VarValue), этот макрос установит значение переменной только в том случае, если значение для данной переменной ещё нигде не было определено." - User
"Взводит либо сбрасывает переменную, используемую в качестве флага. Эквивалентно
SET(VarName yes)/SET(VarName no). " - Assistant
"Устанавливает или сбрасывает значение переменной, используемой в качестве флага. Эквивалентно командам
SET(VarName yes)/SET(VarName no)." - 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.
- IsTrue:
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.>,<,>=,<=- бинарные операторы сравнения целых чисел."
- 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.
- IsTrue:
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.>,<,>=,<=- бинарные операторы сравнения целых чисел."
- User
"Работоспособность этой конструкции не гарантируется. Это пока может работать для некоторых типов модулей, а для других работать не будет. Мы не рекомендуем использовать разные типы модуля по однному пути в разных случаях в принципе, но если это необходимо, то правильный способ - убрать под
IFвесь модуль и вынести общую часть черезINCLUDE." - Assistant
"Работоспособность этой конструкции не гарантируется. В настоящее время она может работать для некоторых типов модулей, но не для всех. Мы не рекомендуем использовать разные типы модулей по одному пути в различных ситуациях. Однако, если это необходимо, правильный подход - обернуть весь модуль в условную конструкцию
IFи вынести общую часть черезINCLUDE." - User
"- Если
KINDуказан какSTATUSили не указан, то сообщение выводится предупреждение.- Если
KINDуказан какFATAL_ERROR, то сообщение выводится как configure-ошибка и сборка останавливается."
- Если
- Assistant
- Если
KINDуказан какSTATUSили не указан, то сообщение выводится как предупреждение. - Если
KINDуказан какFATAL_ERROR, то сообщение выводится как ошибка конфигурации и сборка останавливается.
- Если
- User
"Выдать предупреждение или ошибку, если модуль попал в сборку в нарушение условий, выраженных
COND_VARS.- Макрос
BUILD_ONLY_IFвыдаёт ошибку, если все переменныеCOND_VARSне определены или имеют значение ложь (false,f,no,off,0) и, соответственно, не выдаёт, если хотя бы для одной переменной это не выполнено. - Макрос
NO_BUILD_IFвыдаёт ошибку, если хотя бы одна переменная определена и не имеет значение ложь (т.е. значение отличное отfalse,f,no,off,0)."
- Макрос
- Assistant
"Выдает предупреждение или ошибку, если модуль попал в сборку, нарушая условия, выраженные в
COND_VARS.- Макрос
BUILD_ONLY_IFвыдает ошибку, если все переменныеCOND_VARSне определены или имеют значение ложь (false,f,no,off,0). В противном случае ошибка не выдается. - Макрос
NO_BUILD_IFвыдает ошибку, если хотя бы одна переменная изCOND_VARSопределена и не имеет значение ложь (т.е. значение отличается отfalse,f,no,off,0)."
- Макрос
- User
"Параметры:
STRICT(режим по умолчанию) управляет интерпретациейbob.makeпри нарушении условий. Если выставлен, то модуль и все вариантыRECURSEв его bob.make будет проигнорированы. Это приведёт к тому, что модуль не будет собираться и станет недоступен для зависимостей поPEERDIRиDEPENDS. Также не станут собираться модули, достижимые только от этого поRECURSE, например его тесты.FATAL_ERRORуправляет тем, должна ли выдаваться ошибка или только предупреждение при нарушении условий. Он также безусловно включаетSTRICT-режим интепретации (см.выше).WARNINGне влияет на сборку, только выдаёт configure warning при нарушении условий."
- Assistant
Параметры:
STRICT(режим по умолчанию) управляет интерпретациейbob.makeпри нарушении условий. Если установлен, модуль и все варианты, указанные в его секцииRECURSE, будут проигнорированы. Это приведёт к тому, что модуль не будет собираться и станет недоступен для зависимостей, определённых черезPEERDIRиDEPENDS. Также не будут собираться модули, достижимые только через данный модуль поRECURSE, например его тесты.FATAL_ERRORопределяет, должна ли выдаваться ошибка или только предупреждение при нарушении условий. Этот параметр также безусловно включаетSTRICT-режим интерпретации (см. выше).WARNINGне влияет на сборку, а только выдает предупреждение (configure warning) при нарушении условий.
- User
"Эти макросы по умолчанию работают в режиме
STRICT. В случаеWARNINGбудет лишь выдано предупреждение на консоль, и сборка продолжится. Модуль либо соберётся в запрещённой конфигурации, либо случится ошибка сборки.В случае с
FATAL_ERRORилиSTRICTмодуль будет исключён из сборки с соответственно configure-ошибкой или предупреждением.PEERDIR-зависимости на такой модуль выдадут дополнительные configure-ошибки. Если будут проигнорированы с помощью параметра-k(--keep-going), то возникнут ошибки линковки." - Assistant
Эти макросы по умолчанию работают в режиме
STRICT. В случае использования параметраWARNINGбудет выдано только предупреждение на консоль, и сборка продолжится. Модуль либо соберется в запрещенной конфигурации, либо произойдет ошибка сборки.В случае использования параметров
FATAL_ERRORилиSTRICT, модуль будет исключен из сборки с соответствующей ошибкой конфигурации или предупреждением. Зависимости черезPEERDIRна такой модуль вызовут дополнительные ошибки конфигурации. Если такие ошибки будут проигнорированы с помощью параметра-k(--keep-going), то произойдут ошибки на этапе линковки. - User
"Позволяет указать владельца кода в данной директории. Владелец автоматически добавляется во все ревью, затрагивающие код, сборка которого описывается в данном
bob.makeфайле. Таким кодом считается код, из которого строится модуль, описанный в данномbob.make, либо самbob.makeфайл, если в нём нет модулей, а только перечисление подпроектов черезRECURSE.При указании имени пользователя используется логин. Группы описываются в самой проекте в папке [groups]
Данный макрос должен использоваться обязательно. При этом настоятельно рекомендуется использовать группы, а не отдельных людей, чтобы не возникали ситуации, когда, некоторый код поддерживается бывшим сотрудником (т.е. никем).
Для нахождения владельцев кода в директориях без собственного
bob.make(т.е. которые напрямую не указаны ни в одномbob.make) берётся первый найденныйbob.makeвыше по иерархии директорий. Если в первом найденномbob.makeне будет указанOWNER, то директория будет считаться бесхозной, даже если еще выше по иерархии естьbob.makeс указаннымOWNER." - Assistant
"Позволяет указать владельца кода в данной директории. Владелец автоматически добавляется во все ревью, касающиеся кода, сборка которого описана в данном
bob.makeфайле. Таким кодом считается код, из которого строится модуль, описанный в данномbob.make, либо самbob.makeфайл, если он содержит только перечисление подпроектов черезRECURSE, но не содержит модулей.При указании владельца используется логин пользователя. Группы описываются в проекте в папке [groups].
Этот макрос должен использоваться обязательно. При этом настоятельно рекомендуется назначать владельцами группы, а не отдельных людей, чтобы избежать ситуаций, когда код остается неподдерживаемым после ухода сотрудника.
Для определения владельцев кода в директориях без собственного
bob.make(т.е. которые напрямую не указаны ни в одномbob.make), берется первый найденныйbob.makeвыше по иерархии директорий. Если в первом найденномbob.makeне будет указанOWNER, то директория будет считаться бесхозной, даже если еще выше по иерархии естьbob.makeс указаннымOWNER." - User
Перефразируй "Параметры и их семантика полностью аналогичны макросу
OWNER.Позволяет указать отдельную группу людей, которые будут получать оповещения об изменениях в коде, сборка которого описывается данным bob.make файлом. Данный макрос не налагает на описанных в нём людей ответственности, связанной с владением кодом, но позволяет отслеживать изменения. В будущем планируются доработки, позволяющие подписчикам более гибко управлять нотификациями от разных проектов."
- Assistant
"Параметры и их семантика полностью аналогичны макросу
OWNER.Позволяет указать отдельную группу людей, которые будут получать уведомления о изменениях в коде, сборка которого описана в данном bob.make файле. Этот макрос не накладывает на указанных людей ответственность за владение кодом, но позволяет им отслеживать изменения. В будущем планируется внедрение доработок, позволяющих подписчикам более гибко управлять уведомлениями от различных проектов."
- 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()). Он пишется только в глобальном скоупе." - 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()). Он пишется только в глобальном скоупе." - User
"### PEERDIR
PEERDIR(Dirs..)Основной макрос указания зависимостей между модулями. Зависимости указываются ссылкой на директорию, в которой размещён файл
bob.makec описанием сборки модуля, от которого данный модуль зависит.Чтобы
PEERDIRбыл корректным, должна существовать директория, указанная в нём, в ней должен быть файлbob.makeи этот файл должен описывать сборку модуля. Если что-то из этого не выполнено, то будет выдана ошибка конфигурацииBadDir.Модуль, в котором написан
PEERDIR, зависит от модуля, на который этотPEERDIRссылается.PEERDIRинтерпретируется с учётом типа модуля, в котором он указан. Он может обозначать один из двух вариантов зависимостей:- Для программ и подобных им модулей
PEERDIRозначает включение или необходимость для сборки, т.е. модули вPEERDIRявляются составными частями или требуются в построенном виде для построения данного. Например, библиотеки включаются в программы, а пакеты в go используют зависимые пакеты для собственной сборки. - Для библиотек и подобных им модулей
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." - Для программ и подобных им модулей
- Assistant
PEERDIR
PEERDIR(Dirs..)Основной макрос для указания зависимостей между модулями. Директория, указанная в
PEERDIR, должна содержать файлbob.makeс описанием сборки модуля, от которого зависит данный модуль.Чтобы
PEERDIRбыл корректным, необходимо выполнение следующих условий:- Директория должна существовать.
- В этой директории должен быть файл
bob.make. - Файл
bob.makeдолжен описывать сборку модуля.
Если хотя бы одно из этих условий не выполнено, будет выдана ошибка конфигурации
BadDir.Модуль, в котором указан
PEERDIR, зависит от модуля, на который ссылается этотPEERDIR.PEERDIRинтерпретируется с учетом типа модуля, в котором он указан, и может обозначать один из двух вариантов зависимостей:- Для программ и подобных им модулей
PEERDIRозначает включение или необходимость для сборки. То есть, модули вPEERDIRявляются составными частями или необходимы в построенном виде для сборки данного модуля. Например, библиотеки включаются в программы, а пакеты в go требуют зависимых пакетов для своей сборки. - Для библиотек и подобных им модулей
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. - 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-библиотеки с кодом. Таким образом, в реальности эта зависимость превращается в зависимость одного теста от библиотеки с кодом другого. В частности, это означает, что при запуске зависящего теста зависимый запущен не будет."
- Промежуточные модули (вроде
- 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-библиотеку с кодом. Таким образом, в реальности эта зависимость превращается в зависимость одного теста от библиотеки с кодом другого теста. Это означает, что при запуске зависимого теста зависимый тест сам по себе не будет запущен.
- Промежуточные модули (например,
- 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." - Для мультимодуля типа
- 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. - Для мультимодуля типа
- User
"Добавляет в сборку один файл исходного кода.
Файл будет обработан на основе его расширения. К стандартной обработке будут добавлены флаги Flags... специфичные для команды обработки этого типа файлов (напр. флаги компиляции для С++)."
- Assistant
"Добавляет один файл исходного кода в сборку.
Файл будет обработан на основе его расширения. При стандартной обработке будут также применены флаги Flags..., специфичные для команды обработки этого типа файлов (например, флаги компиляции для C++)."
- 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 на выходе)."
- Макрос
- 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на выходе)."
- В модулях типа
- 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
- Мы не рекомендуем использовать макрос
SRCDIRбез необходимости: в большинстве случаев он осложняет понимание описания сборки поскольку скрывает реально размещение исходных файлов из макросов. - Не используйте макрос
SRCDIRчтобы использовать один и те же исходные файлы в разных модулях. Каждый файл анализируется системой сборки один раз и воровство исходных файлов может приводить к потерянным зависимостям, неоднозначностям описания сборки и другим проблемам."
- Директории в дереве исходного кода должны указываться от корня Аркадии, указание
- 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:- Мы не рекомендуем использовать макрос
SRCDIRбез необходимости: в большинстве случаев он усложняет понимание описания сборки, так как скрывает реальное расположение исходных файлов в макросах. - Не используйте макрос
SRCDIR, чтобы переиспользовать одни и те же исходные файлы в разных модулях. Каждый файл анализируется системой сборки один раз, и такое воровство исходных файлов может привести к пропущенным зависимостям, неоднозначностям в описании сборки и другим проблемам.
- Директории в дереве исходного кода должны указываться от корня Аркадии, указание
- 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действует только на модули, зависящие от данного напрямую. Для такого поведения есть два сценария:- Путь поиска для приватного интерфейса, который должен использоваться только другими частями реализации библиотеки, но не должен быть доступен внешним пользователям.
- Путь поиска обеспечивает резолвинг локальных файлов с распространёнными именами (например,
stdio.hилиconfig.h). В норме такие имена должны ссылаться или на стандартную библиотеку или на файл той библиотеки, к которой относится код.ADDINCL(GLOBAL)привёл бы к нежелательному резолвингу в зависящих модулях, а писатьADDINCL()во всех прямых пользователях может быть неудобно и тяжело в поддержке.
В макросе
ADDINCL:- Директории в дереве исходного кода должны указываться от корня репозитория проекта, указание
${BUILD_ROOT}не обязательно. - Директории в дереве генерированных файлов (если хочется указывать генерированные файлы не от корня) должны быть обязательно указаны от корня с указанием самого корня, т.е.
${DIR_BUILD_ROOT}/1st_level_dir/subdir
Рекомендуется все импорты и инклуды делать только от корня репозитория проекта, механизм
ADDINCLпредназначен для работы сcontribкодом либо кодом, который выкладывается вopensource." - 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действует только на модули, напрямую зависящие от данного. Такое поведение может применяться в двух сценариях:- Путь поиска для приватного интерфейса, который должен использоваться только другими частями реализации библиотеки, но не должен быть доступен внешним пользователям.
- Путь поиска обеспечивает резолвинг локальных файлов с общими именами (например,
stdio.hилиconfig.h). Обычно такие имена должны ссылаться на стандартную библиотеку или на файл той библиотеки, к которой относится код. ИспользованиеADDINCL(GLOBAL)привело бы к нежелательному резолвингу в зависящих модулях, и добавлениеADDINCL()во всех прямых пользователях может быть неудобным и сложным в поддержке.
При использовании макроса
ADDINCL:- Директории в дереве исходного кода должны указываться от корня репозитория проекта, указание
${BUILD_ROOT}не обязательно. - Директории в дереве сгенерированных файлов (если требуется указание генерированных файлов не от корня) должны быть указаны от корня с указанием самого корня, например
${DIR_BUILD_ROOT}/1st_level_dir/subdir.
Рекомендуется указывать все импорты и инклуды от корня репозитория проекта. Механизм
ADDINCLпредназначен для работы сcontribкодом или кодом, который выкладывается вopensource. - 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 макросом-источником." - В
- 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с макросом-источником. - В