Привет, ты технический писатель с опытом работы более 5 лет. Ты писал документацию на…
- User
Привет, ты технический писатель с опытом работы более 5 лет. Ты писал документацию на системы сборки и утилиты maven, gcc, brew. Сейчас тебе необходимо написать документацию на систему сборки byb make. Команды сборки интегрированы в универсальную утилиту byb. Инженеры дали тебе описание системы сборки "byb — сложная утилита с большим количеством подкоманд, у каждой из которых существует большое количество опций, меняющих поведение утилиты. Для того чтобы удобно задавать, менять и управлять настройками исполнения, есть несколько способов:
Аргументы командной строки (аргумент --help или -h/-hh/-hhh покажет доступные аргументы) Переменные окружения (чаще всего начинаются с префикса byb_) Файлы byb.conf в формате toml Как сгенерировать byb.conf
Формат byb.conf должен быть представлен в виде toml файла. Для опций без параметров следует указывать true в качестве значения. Для опций "словарей" (например flags), следует открывать одноимённую секцию (таблицу), где дальше будут следовать записи в формате key = "val". Например:
[flags] NO_DEBUGINFO = "yes" Порядок применения опций Места возможных расположений файла с опциями byb (каждый последующий может переопределять поля предыдущего):
arcadia/junk/arcadia/../byb.conf (если вы хотите иметь разный конфиг для разных репозиториев) ~/.byb/byb.conf переменные окружения аргументы командной строки Так же есть возможность менять имя byb.conf (каждый последующий может переопределять поля предыдущего):
byb.conf (сначала обрабатывается файл из корня аркадии, потом из junk, ...) byb.{command}.conf Модификаторы {system} влияют на то, из какой подкомманды (handler) и на какой системе (windows, linux, darwin, java, unknown) будет применяется данный файл конфигурации. То есть, например, чтобы конфигурация применялась для хэндлера make на платформе darwin достаточно создать в одном из удобных мест файл с названием, например, byb.make.darwin.conf.
Опции для конкретных команд byb Если одна и та же опция используется в нескольких хендлерах и вам нужны, в зависимости от хендлера, разные значения, можно точно указать нужный хендлер и переопределить опции только для него. Например:
project_output = "/default/path"
[ide.qt] project_output = "/path/to/qt/project"
[ide.msvs] project_output = "c:\path\to\msvs\project" Таким образом byb ide qt и byb ide msvs будут иметь разные пути до проекта, отличные от значения по умолчанию.
Пример с переопределением словарной опции flags только для хендлера byb dump json-test-list
[flags] NO_DEBUGINFO = "yes"
[dump.json-test-list.flags] MY_SPECIAL_FLAG = "yes" Вызов byb dump json-test-list в этом случае будет эквивалентен byb dump json-test-list -DMY_SPECIAL_FLAG="yes", NO_DEBUGINFO не будет использоваться.
Подстановка переменных окружения Строковые ключи могут указывать переменные окружения в формате {byb_ARCADIA_ROOT}/../out"
Изменение цветовой схемы byb по умолчанию Для колоризации byb использует внутри текста свои маркеры, которые при выводе на терминал изменяют цвет последующего текста:
alt1 = "cbybn" alt2 = "magenta" alt3 = "light-blue" bad = "red" good = "green" imp = "light-default" path = "yellow" unimp = "dark-default" warn = "yellow" Значения по умолчанию можно изменить с помощью секции terminal_profile в конфиге, например:
[terminal_profile] bad = "light-red" unimp = "default" Добавление целевых платформ Подробнее про платформы можно найти в документации по byb make. Подробнее о том, как добавить целевые плафтормы через командную строку.
Чтобы добавить интересующие целевые платформы, достаточно несколько раз описать следующую конструкцию:
[[target_platform]] platform_name = "default-darwin-arm64" build_type = "relwithdebinfo"
[target_platform.flags] ANY_FLAG = "flag_value" ANY_OTHER_FLAG = "flag_value" На каждый параметр командной строки --target-platform-smth существует аналогичный ключ для файла конфигурации.
Внимание
Не нужно добавлять целевые платформы в файлы конфигурации внутри аркадии — эта конфигурация автоматически применится на всех машинах.
Описание дополнительных опций (alias) Если есть необходимость постоянно задавать одни и те же аргументы, их можно объединить в alias. Для описания alias-ов используется синтаксис toml Array of Tables.
Пример: --add-go-result Например, если нужно добавить симлинки на сгенерированные go файлы, приходится писать что-то подобное:
byb make path/to/project --replace-result --add-result=.go --no-output-for=.cgo1.go --no-output-for=.res.go --no-output-for=_cgo_gotypes.go --no-output-for=_cgo_import.go В качестве решения можно записать всё в файл junk//byb.make.conf следующие строки:
junk//byb.make.conf
replace_result = true # --replace-result add_result_extend = [".go"] # --add-result=.go suppress_outputs = [".cgo1", ".res.go", "_cgo_gotypes.go"] # ----no-output-for=.cgo1.go --no-output-for=.res.go --no-output-for=_cgo_gotypes.go В таком случае значения будут применяться всегда (при всех запусках byb make для пользователя ). Если же необходимо иметь возможность включать данное поведение, можно использовать технологию alias-ов:
junk//byb.conf
^ alias will be available only for user
^ in any handler
[[alias]] # define new alias
Any keys, available in byb.conf
replace_result = true
add_result_extend = [".go"] suppress_outputs = [".cgo1", ".res.go", "_cgo_gotypes.go"] [alias._settings.arg] # define argument for this alias names = ["--add-go-result"] # define only long name help = "Add generated .go files" # define help string visible = true # make this argument visible inbyb make --helpТеперь флаг --add-go-result виден в выводе byb make --help, и мы можем сократить команду до:byb make path/to/project --add-go-result Пример: отключение предпостроенных тулов Чтобы отключить использование предпостроенных тулов, нужно запускать byb со следующими аргументами:
byb make path/to/project -DUSE_PREBUILT_TOOLS=no --host-platform-flag=USE_PREBUILT_TOOLS=no Сначала опишем желаемое поведение в byb.conf:
[host_platform_flags] USE_PREBUILT_TOOLS = "no"
[flags] USE_PREBUILT_TOOLS = "no" Теперь опишем alias, который будет включаться по аргументу, переменной окружения или выставлением значения в любом byb.conf:
[[alias]] [alias.host_platform_flags] # host_platform_flags is subkey for alias USE_PREBUILT_TOOLS = "no"
[alias.flags] # flags is subkey for alias USE_PREBUILT_TOOLS = "no"
[alias._settings.arg] # define argument names = ["-p", "--disable-prebild-tools"] # define short and long name help = "Disable prebuild tools" visible = true
[alias._settings.env] # define environment value name = "byb_DISABLE_PREBUILD_TOOLS"
[alias._settings.conf] # define config key name = "disable_prebuild_tools" Теперь, чтобы активировать это поведение, можно воспользоваться следующими способами:
Long argument
byb make path/to/project --disable-prebuild-tools
Short argument
byb make path/to/project -p
Env
byb_DISABLE_PREBUILD_TOOLS=yes byb make path/to/project
Config value
echo "\ndisable_prebuild_tools=true\n" >> junk/$USER/byb.conf byb make path/to/project Несколько alias-ов Можно создавать любое количество alias-ов внутри одного файла. Alias-ы из разных файлов не перезаписывают друг друга. Задавать описанную переменную в блоке [alias._settings.conf] можно в любом файле, в любом месте, так как создание alias-ов происходит до применения значений из файлов конфигурации.
path/to/first/byb.conf
some_values = true
third_alias = true
[[alias]]
...
[alias._settings.conf] name = "first_alias"
[[alias]]
...
path/to/second/byb.conf
some_other_values = true [[alias]]
...
[alias._settings.conf] name = "third_alias"
[[alias]] first_alias = true
...
Пример с target_platform [[alias]]
[[alias.target_platform]] # --target-platform platfom_name = "..." build_type = "debug" # --target-platform-debug run_tests = true # --target-platform-tests target_platform_compiler = "c_compiler" # --target-platform-c-compiler
...
[alias.target_platform.flags] # --target-platform-flag FLAG = true OTHER_FLAG = "other_value"
[alias._settings.arg] # Create argument consumer for alias names = ["-a", "--my-cool-alias"] # Short and long name help = "This alias are awesome! It really helps me" # Help string visible = true # make it visible in
byb make --help[alias._settings.env] # Create environment consumer for alias, must starts with byb name = "byb_MY_COOL_ALIAS" [alias._settings.conf] # Create config consumer for alias, can be enabled from any config-file name = "my_cool_alias" Семантика alias Внутри одного блока [[alias]] можно задавать произвольное количество опций и под-опций. Для создания аргумента или переменной окружения нужно описать их в ключах [alias._settings.arg] и [alias._settings.env], как показано в примере. После этого они станут доступными во всех подкомандах byb. Для создания опции, которая будет существовать только в конкретном handler-е (например make), достаточно дописать между ключами alias и settings произвольный префикс:[alias.make._settings.args] — будет работать только в byb make ... [alias.ide.idea._settings.args] — будет работать только в byb ide idea ... При заполнении ключа [alias._settings.conf] создаётся опция, которую можно явно включить в любом конфигурационном файле (даже в том, который применился раньше — поиск и обработка alias-ов происходит до применения значений). Более того, появляется возможность применять один alias внутри другого, обеспечивая таким образом простейшую композицию.
Внимание
Пока мы не рекомендуем использовать композицию — byb может вести себя непредсказуемо. Но мы будем рады, если вы попробуете :)
Важно
Переменные окружения и опции в файлах конфигурациях не могут иметь значений, отличных от булевых, при этом если в значение передано false, соответствующий alias не активируется. Аргумент является флагом и не может принимать никаких значений.
Обо всех проблемах и идеях улучшений смело рассказывайте в очередь DEVTOOLSSUPPORT
Композиция Если возникла необходимость вынести общую часть из alias-ов, можно воспользоваться композицией. Пусть у нас есть два alias-а:
[[alias]] first_value = 1 second_value = 2 [[alias._settings.arg]] names = ["--first"]
[[alias]] second_value = 2 third_value = 3 [[alias._settings.arg]] names = ["--second"] Чтобы вынести общую часть, нужно создать новый alias c параметром конфигурации:
[[alias]] second_value = 2 [[alias._settings.conf]] name = "common_alias"
[[alias]] first_value = 1 common_alias = true # Call alias [[alias._settings.arg]] names = ["--first"]
[[alias]] common_alias = true # Call alias third_value = 3 [[alias._settings.arg]] names = ["--second"] Теперь, при вызове byb --second применится alias common_alias, и выставится значение для third_value.
Особенности:
Можно вызывать несколько alias-ов внутри другого alias-а Глубина «вложенности» может быть любой Есть защита от циклов Можно использовать alias, объявленный позже места использования или находящийся в другом файле " Напиши документацию
- Assistant
Документация по системе сборки byb make
Введение
Система сборки
byb makeвключена в универсальный инструментарийbyb, представляющий собой мощную систему с множеством подкоманд. Каждая из этих подкоманд имеет ряд опций, влияющих на ее поведение. В данной документации представлен обзор ключевых аспектов конфигурации и использованияbyb make.Настройка и конфигурация
Способы задания настроек:
- Аргументы командной строки: Используйте
--helpили-h/-hh/-hhhдля просмотра доступных аргументов. - Переменные окружения: Названия чаще всего начинаются с
byb_. - Файлы конфигурации
byb.conf: Форматированные по правилам TOML.
Создание byb.conf
Формат файла:
- Файл должен быть в формате TOML.
- Для опций без параметров укажите
true. - Для "словарных" опций используйте секции, например:
[flags] NO_DEBUGINFO = "yes"Порядок применения опций:
$arcadia/byb.conf$arcadia/junk/${USER}/byb.conf$arcadia/../byb.conf(для разных репозиториев)~/.byb/byb.conf- Переменные окружения
- Аргументы командной строки
Изменение имени byb.conf:
Имя файла
byb.confможет быть модифицировано для более детальной настройки, используя модификаторы${command}и${system}.Опции для конкретных команд byb:
Можно точно указать нужный хендлер и переопределить опции только для него, например:
project_output = "/default/path" [ide.qt] project_output = "/path/to/qt/project" [ide.msvs] project_output = "c:\\path\\to\\msvs\\project"Подстановка переменных окружения:
Строковые ключи могут содержать переменные окружения в формате
${ENV_VAR}.Изменение цветовой схемы byb по умолчанию:
Используйте секцию
terminal_profileв конфиге для изменения цветов по умолчанию.Добавление целевых платформ:
Описание целевых платформ находится в документации
byb make. Добавление осуществляется через конструкцию[[target_platform]].Alias в byb.conf
Можно определить alias для группировки часто используемых аргументов. Alias определяется через TOML Array of Tables. Примеры использования alias помогут сократить команды и сделать работу с
byb makeболее удобной.Примеры alias:
Добавление .go файлов:
[[alias]] replace_result = true add_result_extend = [".go"] suppress_outputs = [".cgo1", ".res.go", "_cgo_gotypes.go"]Отключение предпостроенных тулов:
[[alias]] [alias.host_platform_flags] USE_PREBUILT_TOOLS = "no" [alias.flags] USE_PREBUILT_TOOLS = "no"Композиция alias
Композиция позволяет создавать мощные конструкции конфигурации, извлекая общие части alias в отдельные блоки.
Пример:
[[alias]] second_value = 2 [[alias._settings.conf]] name = "common_alias" [[alias]] first_value = 1 common_alias = true [[alias._settings.arg]] names = ["--first"] [[alias]] common_alias = true third_value = 3 [[alias._settings.arg]] names = ["--second"]Заключение
Документация представляет собой лишь основы настройки и использования
byb makeи не охватывает все возможные аспекты и подробности обширного инструментарияbyb. Для дополнительной информации и специфических случаев пользуйтесь документацией конкретных подкоманд и опций. - Аргументы командной строки: Используйте