Skip to content
TheChatArchiveThe Chat Archive
gpt-4-0125-preview· openaiHugging Face Suzhen/CodeChat

Привет, ты технический писатель с опытом работы более 5 лет. Ты писал документацию на…

  1. 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/byb.confarcadia/byb.conf arcadia/junk/USER/byb.conf{USER}/byb.conf arcadia/../byb.conf (если вы хотите иметь разный конфиг для разных репозиториев) ~/.byb/byb.conf переменные окружения аргументы командной строки Так же есть возможность менять имя byb.conf (каждый последующий может переопределять поля предыдущего):

    byb.conf (сначала обрабатывается файл из корня аркадии, потом из junk, ...) byb.system.confbyb.{system}.conf byb.{command}.conf Модификаторы commandи{command} и {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 не будет использоваться.

    Подстановка переменных окружения Строковые ключи могут указывать переменные окружения в формате ENVVAR,которыебудутподменятьсяпослезагрузкиконфигов.ДополнительнорезолвитсяпеременнаяокруженияbybARCADIAROOT,котораяуказываетнаАркадию,изкоторойработаетbyb.Например:outputroot="{ENV_VAR}, которые будут подменяться после загрузки конфигов. Дополнительно резолвится переменная окружения byb_ARCADIA_ROOT, которая указывает на Аркадию, из которой работает byb. Например: output_root = "{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 in byb 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, объявленный позже места использования или находящийся в другом файле " Напиши документацию

  2. Assistant

    Документация по системе сборки byb make

    Введение

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

    Настройка и конфигурация

    Способы задания настроек:

    1. Аргументы командной строки: Используйте --help или -h/-hh/-hhh для просмотра доступных аргументов.
    2. Переменные окружения: Названия чаще всего начинаются с byb_.
    3. Файлы конфигурации byb.conf: Форматированные по правилам TOML.

    Создание byb.conf

    Формат файла:
    • Файл должен быть в формате TOML.
    • Для опций без параметров укажите true.
    • Для "словарных" опций используйте секции, например:
    [flags]
    NO_DEBUGINFO = "yes"
    
    Порядок применения опций:
    1. $arcadia/byb.conf
    2. $arcadia/junk/${USER}/byb.conf
    3. $arcadia/../byb.conf (для разных репозиториев)
    4. ~/.byb/byb.conf
    5. Переменные окружения
    6. Аргументы командной строки
    Изменение имени 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. Для дополнительной информации и специфических случаев пользуйтесь документацией конкретных подкоманд и опций.