Skip to content

package.md

Latest commit

 

History

History
196 lines (163 loc) · 15.4 KB

package.md

File metadata and controls

196 lines (163 loc) · 15.4 KB
Raw

ya package

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

Синтаксис

Общий формат команды выглядит следующим образом:

ya package [OPTION]... [PACKAGE DESCRIPTION FILE NAME(S)]...

где:

  • [OPTION] — дополнительные флаги или ключи, которые модифицируют поведение выбранной подкоманды;
  • [PACKAGE DESCRIPTION FILE NAME(S)] — названия файлов описания пакета в формате JSON (package.json).

Принцип работы

Для сборки пакета нужно запустить команду с указанием пути к JSON-описанию и необходимого формата. Пакет будет собран в текущей директории. Если формат пакетирования не указан в аргументах и не описан в файле описания пакета, будет создан tar-архив.

ya package devtools/project/package/hello_world.json

Результат выполнения

tar -tvzf ./some-package-hello-world.85c7e374108166bfc1b2a47ca888830965a07708.tar.gz
drwxrwxr-x 0/0 0 2021-03-11 06:58 some_package_dir/
-rwxrwxr-x 0/0 19488 2021-03-11 06:58 some_package_dir/hello_world

Получаем архив с исполняемым файлом внутри директории some_package_dir.

Описание архива:

{
    "meta": {
        "name": "some-package-hello-world",
        "maintainer": "Programmers <mail>",
        "description": "hello world test package",
        "version": "{revision}"
    },
    "build": {
        "targets": [
            "devtools/project/hello_world"
        ]
    },
    "data": [
        {
            "source": {
                "type": "BUILD_OUTPUT",
                "path": "devtools/project/hello_world/hello_world"
            },
            "destination": {
                "path": "/some_package_dir/"
            }
        }
    ]
}

В данном описании определены:

  • Имя пакета:some-package-hello-world
  • Версия пакета: текущая ревизия репозитория, определяемая автоматически
  • Содержимое пакета: собираемая для пакета программа devtools/project/hello_world будет помещена в каталог some_package_dir.

По умолчанию ya package создает пакет в текущем каталоге. С помощью опций -O/--package-output вы можете переопределить каталог, куда ya package сохранит создаваемые пакеты.

Содержимое файла package.json

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

Файл package.json содержит информацию о:

  • конфигурации сборки: целевых программах, сборочных флагах, платформах и прочем;
  • зависимостях из репозитория и ресурсах;
  • способах раскладки артефактов внутри пакета, правах доступа, именах файлов и каталогов;
  • метаданных, относящихся к пакету и его сборке;
  • параметрах пакетирования, непосредственно связанных с описываемым пакетом.

В большинстве случаев для сборки пакета определенной версии достаточно запустить команду ya package <package-path> в контексте конкретной ревизии репозитория.

Формат описания использует специальные секции с параметрами:

  • meta — секция метаинформации с названием, версией, описанием пакета и другими полями.
  • include — секция с перечнем путей к другим пакетам, содержимое которых нужно добавить.
  • build — секция с директивами для сборки содержимого пакета командой ya make.
  • data — секция с элементами, которые перемещают или копируют файлы в нужные пути (source и destination).
  • params — секция для указания параметров пакетирования, которые могут быть переопределены командной строкой при запуске ya package.
  • userdata — секция для произвольных пользовательских данных. Не используется и не проверяется ya package.
  • postprocess — секция с описанием действий, которые необходимо выполнить после основной работы ya package.

Поддерживаемые форматы пакетов

Для пакетирования доступны следующие форматы, выбираемые ключом командной строки:

  • --tar — tar-архив (по умолчанию)
  • --debian — deb-пакет
  • --rpm — rpm-пакет
  • --docker — docker-образ
  • --wheel — Python wheel-пакет
  • --aar — aar — нативный пакет для Android
  • --npm — npm-пакет для Node.js

По умолчанию все программы, указанные в package.json, собираются в режиме release.

Например, для сборки Docker-образа используется следующая команда:

ya package <package.json> --docker

Для этого в json-описание пакета нужно добавить Dockerfile, который будет использоваться для последующих вызовов docker build и docker-push. Сам файл не обязательно должен лежать рядом с json-описанием, но обязательно должен иметь /Dockerfile в destination:

{
    "source": {
        "type": "RELATIVE",
        "path": "Dockerfile"
    },
    "destination": {
        "path": "/Dockerfile"
    }
}

Перед вызовом команды docker build в ее рабочей директории производится сборка пакета и подготовка его содержимого. Таким образом при формировании команд в DockerFile (COPY и подобных) можно рассчитывать на наличие файлов и структуру каталогов, описанных в json-описании.

Опции пакетирования

Команда ya package поддерживает множество опций, детали которых можно узнать, запустив ya package --help.

  • --no-cleanup — не очищать временные директории, используется для отладки.
  • --change-log=CHANGE_LOG — текст логов изменений или путь к существующему файлу с логами изменений.
  • --publish-to=PUBLISH_TO — опубликовать пакет в соотвествующем пакетном репозитории.
  • --strip — очистка (стриппинг) бинарных файлов от отладочной информации (только отладочные символы: strip -g).
  • --full-strip — полная очистка (стриппинг) бинарных файлов.
  • --no-compression — не сжиматьtar-архив (только для параметра --tar).
  • --create-dbg — дополнительно создает пакет с отладочной информацией (работает только в случае использования --strip или --full-strip).
  • --key=KEY — ключ для подписи пакета.
  • --wheel-repo-access-key=WHEEL_ACCESS_KEY_PATH — путь к ключу доступа к репозиторию wheel.
  • --wheel-repo-secret-key=WHEEL_SECRET_KEY_PATH — путь к секретному ключу для репозитория wheel.
  • --docker-registry=DOCKER_REGISTRY — реестр Docker.
  • --docker-repository=DOCKER_REPOSITORY — указать приватный репозиторий.
  • --docker-save-image — сохранить Docker-образ в архиве.
  • --docker-push — сохранить Docker-образ в реестре.
  • --docker-network=DOCKER_BUILD_NETWORK — параметр --network для команды docker build.
  • --raw-package — используется с --tar для получения содержимого пакета без упаковки.
  • --raw-package-path=RAW_PACKAGE_PATH — пользовательский путь для параметра --raw-package.
  • --codec=CODEC — имя кодека для сжатия uc.
  • --codecs-list — показать доступные кодеки для сжатия с использованием --uc.
  • --ignore-fail-tests — создать пакет независимо от того, прошли ли тесты или нет.
  • --new — использовать новый формат JSON для ya package.
  • --old — использовать старый формат JSON для ya package.
  • --not-sign-debian — не подписывать debian-пакет.
  • --custom-version=CUSTOM_VERSION — указывает версию пакета.
  • --debian-distribution=DEBIAN_DISTRIBUTION — Debian-дистрибуция (по умолчанию: unstable).
  • --arch-all — использовать "Architecture: all" в debian.
  • --force-dupload — включить dupload --force.
  • -z=DEBIAN_COMPRESSION_LEVEL, --debian-compression=DEBIAN_COMPRESSION_LEVEL — уровень сжатия deb-файла (none, low, medium, high).
  • -Z=DEBIAN_COMPRESSION_TYPE, --debian-compression-type=DEBIAN_COMPRESSION_TYPE — тип сжатия, используемый при создании deb-файла (допустимые типы: gzip, xz, bzip2, lzma, none).
  • --data-root=CUSTOM_DATA_ROOT — путь к пользовательской директории данных, по умолчанию <source root>/../data.
  • --dupload-max-attempts=DUPLOAD_MAX_ATTEMPTS — количество попыток запуска dupload при сбое (по умолчанию: 1).
  • --dupload-no-mail — включить dupload c --no-mail.
  • --overwrite-read-only-files — перезаписывать файлы с правами только на чтение в пакете.
  • --ensure-package-published — убедиться, что пакет доступен в репозитории.

Дополнительные параметры

Основные опции сборки

  • -d — сборка в режиме отладки.
  • -r — сборка в режиме релиза (по умолчанию).
  • --sanitize=SANITIZE — тип санитайзера (address, memory, thread, undefined, leak).
  • --sanitizer-flag=SANITIZER_FLAGS — дополнительные флаги для санитайзера.
  • --lto — сборка с использованием Link Time Optimization (LTO).
  • --thinlto — сборка с использованием ThinLTO.
  • --musl — сборка с использованием библиотеки musl-libc.
  • --afl — использовать AFL вместо libFuzzer.

Поддерживается большинство опций системы сборки ya make.

Запуск тестов

  • -A, --run-all-tests — запускать все тесты при сборке целей из секции build.
  • -t, --run-tests — запускать только быстрые тесты при сборке целей из секции build.
  • --ignore-fail-tests — игнорировать падения тестов при сборке пакетов (иначе сборка пакета будет прервана).
  • --add-peerdirs-tests=PEERDIRS_TEST_TYPE — типы тестов peerdirs (none, gen, all) (по умолчанию: none).

Публикация и загрузка результатов пакетирования

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

  • --publish-to=<repo_url> — опубликовать пакет в соотвествующем пакетном репозитории.
  • --ensure-package-published — проверить доступность пакета после публикации.
  • --upload-resource-type — тип загружаемого ресурса.
  • --artifactory — опубликовать пакет в artifactory (системе хранения собранных бинарных версий компонентов и продуктов).

Для загрузки пакета в Artifactory вам потребуется создать и настроить файл settings.xml. Этот файл хранит настройки, используемые Maven Deploy Plugin. Через этот файл вы можете задекларировать все нужные опции, которые в противном случае пришлось бы передавать напрямую в Maven.

В settings.xml также поддерживается подстановка версии пакета, которая берется из вашего package.json.

Для локальной загрузки данных в Artifactory, выполните команду ya package с дополнительными опциями --artifactory и --publish-to. В опцию --publish-to передайте путь к файлу settings.xml. Путь может быть как абсолютным, так и относительным от корня вашего проекта.

Для передачи пароля используйте опцию --artifactory-password-path, указав путь к файлу с паролем.

ya package --artifactory --publish-to /path/settings.xml --artifactory-password-path /path/password/file