Справочник по Yocto Project (часть 2)

Опубликовано 22.12.2019 автором Nikolai Malykh

Глава 5. Структура каталога исходных кодов

Дерево исходных кодов содержит множество компонент и понимание их роли важно для работы с YP. В этой главе описана структура дерева, а также назначение файлов и каталогов. Рекомендации по организации локального дерева исходного кода даны в разделе Locating Yocto Project Source Files [2].

Система сборки OE не поддерживает имена файлов и каталогов с пробелами.

5.1. Компоненты верхнего уровня

В этом разделе описаны компоненты верхнего уровня в дереве исходных кодов.

5.1.1. `bitbake/`

Этот каталог включает копию BitBake для простоты использования. Копия обычно соответствует текущему стабильному выпуску BitBake. Интерпретатор метаданных BitBake считывает YP Metadata и запускает задачи, определенные в них. Отказы обычно связаны с метаданными, а не с BitBake, поэтому большинству пользователей не нужно думать о BitBake.

Можно запускать исполняемый файл bitbake, хранящийся в каталоге bitbake/bin/. Сценарий настройки окружения oe-init-build-env помещает каталоги сценариев и bitbake/bin (в указанном порядке) в переменную окружения PATH.

Информация о BitBake приведена в [4].

5.1.2. `build/`

Этот каталог содержит пользовательские файлы конфигурации и вывод системы сборки OE в ее стандартной конфигурации, где вывод размещается вместе с деревом исходных кодов. Каталог сборки создается при запуске сценария настройки окружения OE (oe-init-build-env).

Можно отделить вывод и конфигурационные файлы от каталога исходных кодов, указав имя каталога при запуске установочного сценария, описанного в параграфе 5.1.9.1 oe-init-build-env.

5.1.3. `documentation/`

Этот каталог содержит исходные файлы документации YP, а также шаблоны и инструменты для создания руководств в формате PDF и HTML. Каждое руководство размещено в своем каталоге, например, файлы для этого документа расположены в каталоге ref-manual/.

5.1.4. `meta/`

В этом каталоге содержатся метаданные OpenEmbedded-Core, задания, базовые классы, конфигурации машин для эмулируемых платформ (qemux86, qemuarm и т. п.).

5.1.5. `meta-poky/`

Конфигурация для эталонного дистрибутива Poky.

5.1.6. `meta-yocto-bsp/`

Этот каталог содержит эталонные пакеты поддержки плат (BSP). Дополнительные сведения о BSP можно найти в [6].

5.1.7. `meta-selftest/`

Каталог с дополнительными заданиями и файлами добавления, используемые при самотестировании OE для контроля процесса сборки. Если самотестирование не требуется, не следует добавлять этот уровень в свой файл bblayers.conf.

5.1.8. `meta-skeleton/`

Каталог с шаблонами заданий для разработки BSP и ядер.

5.1.9. `scripts/`

Этот каталог содержит сценарии, расширяющие функциональность среды YP (например, QEMU). Сценарий oe-init-build-env добавляет этот каталог в переменную окружения PATH. Каталог включает сценарии, помогающие внести свой вклад в развитие YP, например, create-pull-request и send-pull-request.

5.1.9.1 `oe-init-build-env`

Этот сценарий организует среду сборки OE. Сценарий запускается с помощью команды source и меняет значение переменной PATH, а также устанавливает переменные BitBake с учетом текущего каталога. Сценарий установки окружения нужно запускать до использования команд BitBake. Сценарий использует другие сценарии из каталога scripts для выполнения большого объема работ. При запуске сценария создается рабочая среда YP и каталог сборки (Build Directory), который делается рабочим, а также выводится список базовых целей BitBake, как показано ниже.

     $ source oe-init-build-env

     ### Shell environment set up for builds. ###

     You can now run 'bitbake <target>'

     Common targets are:
         core-image-minimal
         core-image-sato
         meta-toolchain
         meta-ide-support

     You can also run generated qemu images with a command like 'runqemu qemux86'

Сценарий получает принятые по умолчанию значения из файла conf-notes.txt в каталоге meta-poky внутри каталога исходных кодов (Source Directory). Если у вас нестандартный дистрибутив, легко изменить этот конфигурационный файл для включения нужных целей для вашего дистрибутива (Creating a Custom Template Configuration Directory [2]).

По умолчанию при работе этого сценария без аргумента Build Directory создается каталог build в текущем рабочем каталоге. Если аргумент Build Directory задан при запуске сценария, система сборки OE создаст указанный каталог. Например, приведенная ниже команда создаст каталог сборки mybuilds вне дерева исходных кодов.

     $ source oe-init-build-env ~/mybuilds

Система сборки OE использует шаблон конфигурационных файлов, который по умолчанию расположен в каталоге meta-poky/conf каталога исходных кодов (см. раздел Creating a Custom Template Configuration Directory [2]).

Система сборки OE не поддерживает имена файлов и каталогов с пробелами. При попытке запуска сценария oe-init-build-env из каталога с пробелами в имени каталога или содержащихся в нем файлов, сценарий будет завершен с ошибкой, указывающей отсутствие каталога. Убедитесь в том, что имя Source Directory не содержит пробелов.

5.1.10. `LICENSE, READMEиREADME.hardware`

Эти файлы являются стандартными для верхнего уровня.

5.2. Каталог сборки `build/`

Система сборки OE создает сборочный каталог при запуске сценария организации среды (oe-init-build-env). Если сценарию не указан каталог сборки, будет создан каталог buildв текущем каталоге. Переменная TOPDIR указывает на каталог сборки.

5.2.1. `build/buildhistory`

Система сборки OE создает этот каталог при включении функции истории сборки. Каталог отслеживает данные сборки по образам, пакетам и SDK (см. раздел Maintaining Build Output Quality [2]).

5.2.2. `build/conf/local.conf`

Этот файл конфигурации содержит все локальные пользовательские настройки для среды сборки. Опции в файле прокомментированы. Любая переменная, задаваемая здесь, переопределяет заданную в другом месте переменную, если та не использует жесткое кодирование (например, = вместо ?=). Такое кодирование применяется для некоторых переменных, но это происходит достаточно редко.

Следует установить в этом файле для переменной MACHINE значения, соответствующее сборке, указать типы пакетов (PACKAGE_CLASSES) и мест, откуда нужно загружать файлы (DL_DIR).

Если файла local.conf нет, система OE создает его по образцу local.conf.sample при настройке окружения (oe-init-build-env). Используемый образец зависит от переменной $TEMPLATECONF, которая по умолчанию указывает meta-poky/conf при сборке из среду разработки YP и meta/conf при сборке из среды OpenEmbedded-Core. Поскольку переменная в сценарии указывает файл local.conf.sample, это позволяет настроить среду сборки из любого уровня, указав в сценарии настройки окружения на верхнем уровне сборки TEMPLATECONF=your_layer/conf. Когда процесс сборки получает файл-образец, используется утилита sed для подстановки значения ${OEROOT} вместо всех ##OEROOT##.

С использованием переменной TEMPLATECONF можно ознакомиться в файле scripts/oe-setup-builddir дерева исходных кодов. Версия файла local.conf.sample для YP находится в каталоге meta-poky/conf.

5.2.3. `build/conf/bblayers.conf`

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

Если файла bblayers.conf нет при запуске сборки, система OE создает его по образцу bblayers.conf.sample при выполнении сценария настройки среды сборки (oe-init-build-env). Используемый образец зависит от переменной $TEMPLATECONF, которая по умолчанию для среды YP содержит значение meta-poky/conf,а дляOpenEmbedded-Core — meta/conf. Поскольку переменная в сценарии указывает файл bblayers.conf.sample file, это позволяет настроить среду сборки из любого уровня, указав в сценарии настройки окружения на верхнем уровне сборки TEMPLATECONF=your_layer/conf. Когда процесс сборки получает файл-образец, используется утилита sed для подстановки значения ${OEROOT} вместо всех ##OEROOT##.

5.2.4. `build/conf/sanity_info`

Этот файл показывает статус проверки работоспособности и создается в процессе сборки.

5.2.5. `build/downloads/`

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

5.2.6. `build/sstate-cache/`

Этот каталог содержит файлы общего кэша состояний. Каталог можно применять для множества сборок или перенести в другое место, указываемое переменной SSTATE_DIR.

5.2.7. `build/tmp/`

Система сборки OE создает и использует этот каталог для вывода всех результатов сборки. Каталог указывается переменной TMPDIR. При отсутствии каталога BitBake создает его. При необходимости очистить результаты сборки и начать ее с нуля (все кроме загрузки источников) можно удалить содержимое каталога tmp или сам каталог. В этом случае следует также удалить каталог общего кэша состояний build/sstate-cache.

5.2.8. `build/tmp/buildstats/`

Каталог с данными статистики сборки.

5.2.9. `build/tmp/cache/`

При разборе метаданных (задания и файлы конфигурации) BitBake кэширует результаты в каталоге build/tmp/cache/ для ускорения сборки в будущем. Результаты организованы по машинам. При последующей сборке BitBake проверяет каждое задание (вместе с включенными и добавленными к нему файлами) на предмет изменений. Изменения могут детектироваться по времени редактирования файлов (mtime) или хэш-значениям их содержимого. Если файлы не менялись, используется кэшированный результат, а при наличии изменений файлы анализируются заново.

5.2.10. `build/tmp/deploy/`

В этом каталоге содержаться «конечные результаты» процесса сборки OE. Каталог указывается переменной DEPLOY_DIR.Содержимое каталога описано в разделахImages и Application Development SDK [1].

5.2.11. `build/tmp/deploy/deb/`

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

5.2.12. `build/tmp/deploy/rpm/`

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

5.2.13. `build/tmp/deploy/ipk/`

В этом каталоге хранятся файлы . ipk,созданные при сборке.

5.2.14. `build/tmp/deploy/licenses/`

Этот каталог получает данные о лицензировании пакетов. Например, он может содержать подкаталоги для bash, busybox, glibcи т. п., содержащие файлыCOPYING с описанием лицензирования. Информация о лицензировании приведена в разделе Maintaining Open Source License Compliance During Your Product’s Lifecycle [2]).

5.2.15. `build/tmp/deploy/images/`

Этот каталог получает окончательные образы файловых систем. Если полученный образ нужно записать на устройство, его следует искать здесь. Следует соблюдать осторожность при удалении файлов из этого каталога. Можно безопасно удалять старые образы (например, core-image-*), однако загрузчики ядра (*zImage*, *uImage* и т. п.) и дополняющие их файлы могут быть развернуты в каталоге до создания образов. Поскольку эти файлы не создаются непосредственно из образа, при их удалении они не будут автоматически созданы заново при последующей сборке.

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

     $ bitbake -c clean virtual/kernel
     $ bitbake virtual/kernel

5.2.16. `build/tmp/deploy/sdk/`

Система сборки OE создает этот каталог для размещения сценариев установки инструментов, выполнение которых обеспечивает инсталляцию файловой системы sysroot, соответствующей целевой платформе. Описание сценариев установки дано в разделе Building an SDK Installer [7].

5.2.17. `build/tmp/sstate-control/`

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

5.2.18. `build/tmp/sysroots-components/`

Этот каталог содержит компоненты sysroot, которые задача do_prepare_recipe_sysroot указывает (link) или копирует в зависимые от заданий каталоги sysroot каждого задания из DEPENDS. Заполнение этого каталога выполняется через общее состояние, а путь указывается переменной COMPONENTS_DIR. За исключением нескольких экзотических случаев обработка sysroots-components происходит автоматически и заданиям не нужно ссылаться напрямую на build/tmp/sysroots-components.

5.2.19. `build/tmp/sysroots/`

В прежних версиях OE каталог служил для создания глобального общего корня sysroot на уровне машины вместе с естественным sysroot. Начиная с YP 2.7.1, каталоги sysroot размещаются в рабочих каталогах заданий (WORKDIR) и build/tmp/sysroots/ не используется. Однако build/tmp/sysroots/ можно по-прежнему заполнять с помощью команды bitbake build-sysroots и использовать для совместимости. В общем случае использование этого каталога не рекомендуется, следует применять отдельные sysroot для заданий.

5.2.20. `build/tmp/stamps/`

В этом каталоге хранится информация, которую BitBake использует для отслеживания выполняемых задач. Каталог содержит подкаталоги по архитектуре, имени и версии пакета. Например,

     stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do

Хотя файлы в этой структуре не содержат данных, BitBake может отслеживать задачи по именам и временным меткам (см. раздел Stamp Files and the Rerunning of Tasks [1]).

5.2.21. `build/tmp/log/`

Этот каталог содержит журналы сборки, например, вывод задач do_check_pkg и do_distro_check. Запуск сборки не обязательно создает этот каталог.

5.2.22. `build/tmp/work/`

Этот каталог содержит зависимые от архитектуры рабочие каталоги для пакетов, собираемых BitBake. Все задачи выполняются из соответствующих рабочих каталогов. Например, исходные коды для конкретного пакета распаковываются, правятся (patch), настраиваются и компилируются в своем рабочем каталоге. Внутри таких каталогов организация основана на группах пакетов и версиях, для которых будет компилироваться исходный код в соответствии с WORKDIR.

В качестве примера рабочего каталога рассмотрим linux-yocto-kernel-3.0 для машины qemux86. Рабочим каталогом для этого пакета будет tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<…..>, указанный в переменной WORKDIR. В этом каталоге распаковываются исходные коды для linux-qemux86-standard-build, а затем накладываются исправления с помощью Quilt. (см. раздел Using Quilt in Your Workflow [2]). В каталоге linux-qemux86-standard-build создаются стандартные каталоги Quilt linux-3.0/patches и linux-3.0/.pc и могут применяться стандартные команды Quilt.

В WORKDIR создаются и другие каталоги, наиболее важным из которых является WORKDIR/temp/, где хранятся журналы (log-файлы) для каждой задачи в форме log.do_*.pid, а также сценарии BitBake для каждой задачи в форме run.do_*.pid. В каталоге WORKDIR/image/ команда make install размещает выходные файлы, которые затем делятся по пакетам в WORKDIR/packages-split/.

5.2.23. `build/tmp/work/tunearch/recipename/`version`/`

Рабочий каталог задания — ${WORKDIR}. Как описано в параграфе 5.2.19. build/tmp/sysroots/, начиная с выпуска YP 2.7.1, система OE собирает каждое задание в своем каталоге (WORKDIR). Путь к рабочему каталогу создается с использованием архитектуры для данной сборки (например, TUNE_PKGARCH, MACHINE_ARCH
или allarch), имени задания и его версии (например, PE:PV-PR).

В рабочем каталоге каждого задания имеется множество подкаталогов:

${WORKDIR}/temp содержит журналы сборки для каждой задачи, файлы run для каждой выполненной задачи и файл log.task_order, указывающий порядок выполнения задач;
${WORKDIR}/image содержит вывод задачи do_install, соответствующей ее переменной ${D};
${WORKDIR}/pseudo содержит псевдобазу данных и журнал для всех задач pseudo в задании.
${WORKDIR}/sysroot-destdir содержит вывод задачи do_populate_sysroot;
${WORKDIR}/package содержит вывод задачи do_package да разделения по отдельным пакетам;
${WORKDIR}/packages-split содержит вывод задачи do_package после разделения по пакетам с каталогами для каждого пакета, созданного заданием;
${WORKDIR}/recipe-sysroot заполняется зависимостями для цели задания и выглядит подобно целевой файловой системе, включая библиотеки, с которыми заданию может потребоваться связь (например, библиотека C);
${WORKDIR}/recipe-sysroot-native заполняется естественными зависимостями задания и содержит инструменты, требуемые для сборки задания (например, компилятор autoconf, libtool и т. п.).
${WORKDIR}/build применяется лишь для заданий, поддерживающих сборки, где исходный код отделен от результатов; система OE использует этот каталог в качестве отдельного каталога сборки (${B}).

5.2.24. `build/tmp/work-shared/`

Для эффективности система сборки OE создает и использует этот каталог для хранения заданий, использующих общий с другими заданиями рабочий каталог. На практике это применяется для gcc и вариантов (gcc-cross, libgcc, gcc-runtimeи т. п.).

5.3. Метаданные — `meta/`

5.3.1. `meta/classes/`

Этот каталог содержит файлы классов *.bbclass, включающие многократно используемый пакетами код. Каждый пакет наследует класс base.bbclass. Примером другого важного наследуемого класса является autotools.bbclass, теоретически позволяющий любому пакету, основанному на autotools работать с YP без больших усилий. Класс kernel.bbclass содержит базовый код и функции для работы с ядром Linux. Такие функции как генерация образов или подготовка пакетов имеют свои классы (image.bbclass, rootfs_*.bbclass и package*.bbclass). Описанию классов посвящена Глава 6. Классы.

5.3.2. `meta/conf/`

Этот каталог содержит основной набор конфигурационных файлов (начиная с bitbake.conf) в которые включены все остальные файлы конфигурации. Операторы include в конце файла bitbake.conf указывают даже файл local.conf. Хотя bitbake.conf устанавливает принятые по умолчанию значения, их можно переопределить в файле local.conf, а также в файле конфигурации машины или дистрибутива.

5.3.3. `meta/conf/machine/`

Этот каталог содержит файлы конфигурации машины. Если установлено MACHINE
= «qemux86», система сборки OE будет искать файл qemux86.conf в этом каталоге. Каталог include содержит общие данные для разных машин. Если нужна поддержка новой машины в YP, следует заглянуть в этот каталог.

5.3.4. `meta/conf/distro/`

Содержимое этого каталога определяет конфигурацию дистрибутива. Для YP основным файлом служит defaultsetup.conf. Каталог включает версии и определения SRCDATE для настроенных здесь приложений. Примером дополнительной конфигурации может служить poky-bleeding.conf, хотя он в основном наследует конфигурациюPoky.

5.3.5. `meta/conf/machine-sdk/`

Система сборки OE ищет в этом каталоге файлы конфигурации, соответствующие значению SDKMACHINE. По умолчанию в YP включены файлы для 32- и 64-битовых систем x86, поддерживающие некоторые хосты SDK. Можно расширить поддержку SDK, добавив файлы конфигурации в каталоги соответствующих уровней.

5.3.6. `meta/files/`

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

5.3.7. `meta/lib/`

Этот каталог содержит код библиотек OE Python, используемых при сборке.

5.3.8. `meta/recipes-bsp/`

Каталог содержит привязки к конкретному оборудованию или конфигурации для оборудования, такие как u-boot и grub.

5.3.9. meta/recipes-connectivity/

Каталог содержит библиотеки и приложения для коммуникаций с другими устройствами.

5.3.10. meta/recipes-core/

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

5.3.11. meta/recipes-devtools/

Каталог с инструментами, используемыми системой сборки, которые могут применяться и целевой платформой.

5.3.12. `meta/recipes-extended/`

Каталог со второстепенными приложениями, добавляющими свойства к основному образу. Эти приложения могут быть нужны для выполнения требований LSB¹.

5.3.13. `meta/recipes-gnome/`

Каталог, содержащий все, что требуется для приложений GTK+.

5.3.14. `meta/recipes-graphics/`

Каталог с X-библиотеками и другими библиотеками, относящимися к графике.

5.3.15. `meta/recipes-kernel/`

Каталог с ядром и базовыми приложениями и библиотеками, от которых зависит ядро.

5.3.16. `meta/recipes-lsb4/`

Задания, добавленные для поддержки LSB версии 4.x.

5.3.17. `meta/recipes-multimedia/`

Кодеки и утилиты поддержки для звука, изображений и видео.

5.3.18. `meta/recipes-rt/`

Каталог с заданиями для пакетов и образов, применяемых при использовании и тестировании ядер PREEMPT_RT.

5.3.19. `meta/recipes-sato/`

Эталонный дистрибутив Sato, а также связанные с ним приложения и данные конфигурации.

5.3.20. `meta/recipes-support/`

Каталог с заданиями, используемыми другими заданиями, но не включаемыми напрямую в образ (зависимости).

5.3.21. `meta/site/`

Список кэшированных результатов для разных вариантов архитектуры. Поскольку некоторые результаты тестов autoconf не могут быть определены при кросс-компиляции по причине недоступности запуска в live-системе, данные из этого каталога передаются autoconf для разных вариантов архитектуры.

5.3.22. `meta/recipes.txt`

Файл с описанием содержимого recipes-*.

Глава 6. Классы

Файлы классов служат абстракцией функциональности и совместно используются множеством файлов заданий (.bb). Для использования файла класса нужно просто наследовать соответствующий класс в задании. В большинстве случаев наследования класса заданием достаточно для включения функций класса. Однако в некоторых случаях может потребоваться также задание переменных или переопределение принятого по умолчанию поведения.

Любые метаданные, обычно встречающиеся в задании, могут также помещаться в файл класса. Файлы классов используют расширение .bbclass и обычно размещаются в каталоге classes/ каталога meta*/ в дереве исходных кодов. Файлы классов также указываются переменной BUILDDIR (например, build/), как и файлы .conf в каталоге conf. Поиск файлов классов в BBPATH выполняется так же, как и файлов .conf.

В этой главе рассмотрены наиболее важные и полезные классы.

6.1. `allarch.bbclass`

Класс allarch наследуется заданиями, не создающими зависящего от архитектуры вывода. Класс отключает функциональность, которая обычно нужна для создания исполняемых двоичных файлов (например, создание кросс-компилятора и библиотеки C в качестве предварительного условия, а также выделение отладочных символов).

В отличие от заданий для дистрибутивов (например, Debian), задания OE создают пакеты, которые зависят от настройки переменных RDEPENDS и TUNE_PKGARCH
и не должны настраиваться под все архитектуры с помощью allarch. Это происходит даже в тех случаях, когда задание не создает зависимого от архитектуры вывода.

Настройка таких заданий для всех вариантов архитектуры заставляет задачи do_package_write_* tasks иметь разные подписи для машин с разными настройками. Кроме того, происходят ненужные повторы сборки при создании образа для другого значения MACHINE даже при отсутствии изменений в задании.

По умолчанию все задания наследуют классы base и package, которые обеспечивают функциональность, требуемую для создания исполняемых файлов. Если ваше задание, например, производит лишь пакеты с файлами конфигурации, медиа-файлами или сценариями (например, Python и Perl), им нужно наследовать класс allarch.

6.2. `archiver.bbclass`

Класс archiver поддерживает выпуск исходных кодов и других материалов в двоичных файлах (архивах). Дополнительная информация об архивах исходных кодов приведена в разделе Maintaining Open Source License Compliance During Your Product’s Lifecycle [2]. В описании переменной ARCHIVER_MODE представлена информация о флагах переменных (varflags), помогающих создавать архивы.

6.3. `autotools*.bbclass`

Классы autotools* поддерживают пакеты с автоматической настройкой. Пакеты autoconf, automakeиlibtool обеспечивают стандартизацию. Классы определяют набор задач (настройка конфигурации, компиляция и т. п.), которые работают с автоматическими инструментами. Обычно этого достаточно для задания нескольких стандартных переменных и простого наследования автоматических инструментов. Эти классы могут также работать с эмулируемыми автоматическими инструментами (см. раздел Autotooled Package [2]).

По умолчанию классы autotools* используют сборки за пределами дерева (т. е. сборки autotools.bbclass с B != S). Если собираемая заданием программа не поддерживает сборку вне дерева, следует иметь задание, наследующее класс autotools-brokensep,который ведет себя как классautotools но выполняет сборку с B == S. Этот метод полезен, когда поддержка сборки вне дерева отсутствует или не работает. Однако рекомендуется исправить сборку вне дерева и применять ее по возможности.

Полезно иметь некоторое представление о работе задач, определяемых классами autotools*.

do_configure регенерирует сценарий configure (используя autoreconf) и запускает его со стандартным набором инструментов, применяемых при кросс-компиляции. Можно передать в configure дополнительные параметры через переменную EXTRA_OECONF или PACKAGECONFIG_CONFARGS.
do_compile запускает make с аргументами, задающими компилятор и компоновщик. Можно передать дополнительные параметры через переменную EXTRA_OEMAKE.
do_install запускает makeи передает${D} как DESTDIR.

6.4. `base.bbclass`

Класс base отличается тем, что его неявно наследует каждый файл .bb. Этот класс содержит определения стандартных базовых задач для извлечения исходных файлов, их распаковки, настройки (пусто по умолчанию), компиляции (при наличии Makefile), установки (пусто по умолчанию) и упаковки (пусто по умолчанию). Эти классы часто переопределяются или расширяются другими классами, такими как autotools и package. Класс включает также некоторые функции общего назначения (такие как oe_runmake), запускающие make с аргументами из переменной EXTRA_OEMAKE,а также с аргументами, переданными напрямую вoe_runmake.

6.5. `bash-completion.bbclass`

Организует упаковку и зависимости в соответствии с заданиями, собирающими программы, которые включают данные bash-completion².

6.6. `bin_package.bbclass`

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

Для RPM и других пакетов, не включающих подкаталогов, следует указать соответствующий параметр сборщика, указывающий подкаталог. Например при использовании в BitBake сборщика Git (git://) параметр subpath ограничивает выбор конкретного пути в дереве. Ниже приведен пример, где применяется ${BP} для извлечения файлов в каталог, ожидаемый заданным по умолчанию значением S:

     SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"

Информация о поддерживаемых BitBake сборщиках приведена в разделе Fetchers [4].

6.7. `binconfig.bbclass`

Класс binconfig помогает корректировать пути к сценариям командного процессора. До широкого распространения pkg-config библиотеки распространялись со сценариями (обычно LIBNAME-config) для получения информации о библиотеках и путях к включаемым файлам, нужным программам. Этот класс помогает заданиям применять такие сценарии. При подготовке система сборки OE устанавливает эти сценарии в каталог sysroots/. Наследование этого класса приводит к тому, что все пути в этих сценариях изменяются так, чтобы корректно указывать каталог sysroots/,чтобы все сборки, использующие сценарий, применяли корректные пути для кросс-компиляции (см. описание переменнойBINCONFIG_GLOB.

6.8. `binconfig-disabled.bbclass`

Дополнительный вариант класса binconfig, отключающий двоичные сценарии настройки путем возврата ошибки (в пользу применения pkg-config для запроса информации). Отключаемые сценарии должны быть указаны в переменной BINCONFIG наследующего класс задания.

6.9. `blacklist.bbclass`

Класс blacklist предотвращает сборку системой OE конкретных пакетов («черный список»). Для использования класса нужно наследовать его глобально и установить переменную PNBLACKLISTдля каждого задания, которое вы хотите включить в «черный список». Задайте значениеPN как флаг переменной (varflag) и укажите причину отказа от сборки, которая указывается, если сборка пакета была запрошена. Например, если вы не хотите собирать задание exoticware, можно указать приведенные ниже строки в файле local.conf или конфигурации дистрибутива

     INHERIT += "blacklist"
     PNBLACKLIST[exoticware] = "Not supported by our organization."

6.10. `bluetooth.bbclass`

Класс bluetooth определяет переменную которая расширяет задание (пакет) базовой поддержкой bluetooth для платформы. Описание работы класса приведено в файле meta/classes/bluetooth.bbclass дерева исходных кодов YP.

6.11. `buildhistory.bbclass`

Класс buildhistory записывает историю сборки по метаданным вывода, которую можно использовать для поиска регрессии и анализа вывода сборки. Информация об истории сборки дана в разделе Maintaining Build Output Quality [2].

6.12. `buildstats.bbclass`

Класс buildstats записывает статистику производительности (время, загрузка процессора, ввод-вывод) для каждой задачи в процессе сборки. При использовании этого класса вывод осуществляется в каталог BUILDSTATS_BASE (по умолчанию ${TMPDIR}/buildstats/). Время работы можно анализировать с помощью сценария scripts/pybootchartgui/pybootchartgui.py, который выдает график процесса сборки и позволяет находить узкие места.

Сбор статистики по умолчанию включается переменной USER_CLASSES в файле local.conf. Для отключения следует удалить buildstats из списка USER_CLASSES.

6.13. `buildstats-summary.bbclass`

При глобальном наследовании этот класс выводит статистику в конце сборки. Для работы нужен класс buildstats.

6.14. `ccache.bbclass`

Класс ccache включает кэш компилятора C/C++ для сборки и служит для небольшого повышения производительности сборки. Однако использование класса может давать побочные эффекты, поэтому применять его не рекомендуется (см. http://ccache.samba.org/).

6.15. `chrpath.bbclass`

Класс chrpath служит «оболочкой» для утилиты chrpath, используемой при сборке заданий nativesdk, cross и cross-canadian для изменения записей RPATH в двоичных файлах с целью сделать их перемещаемыми.

6.16. `clutter.bbclass`

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

6.17. `cmake.bbclass`

Класс cmake разрешает рецепты, для которых применяется система сборки CMake. Можно применять переменную EXTRA_OECMAKE для указания дополнительных опций конфигурации, передаваемых команде cmake.

6.18. cml1.bbclass

Класс cml1 обеспечивает базовую поддержку для систем настройки конфигурации в стиле ядра Linux.

6.19. compress_doc.bbclass

Включает компрессию страниц man и info. Класс предназначен для глобального наследования. По умолчанию применяется сжатие gz (gzip), но можно указать иной механизм с помощью переменной DOC_COMPRESS.

6.20. copyleft_compliance.bbclass

Класс copyleft_compliance представляет исходные коды для целей соответствия лицензиям. Этот класс служит альтернативой классу archiver и продолжает применяться, несмотря на отказ от него в пользу archiver.

6.21. `copyleft_filter.bbclass`

Класс, используемый классами archiver и copyleft_compliance для фильтрации лицензий. Класс copyleft_filter является внутренним и не предназначен для использования напрямую.

6.22. `core-image.bbclass`

Класс core-image обеспечивает базовые определения для заданий core-image-*,
такие как поддержка дополнений в IMAGE_FEATURES.

6.23. `cpan*.bbclass`

Классы cpan* поддерживают модули Perl, задания для которых просты и обычно нужны лишь для указания архива исходных кодов и наследования нужного класса. Сборка применяет 2 метода в зависимости от типа модуля:

для модулей на основе старой системы сборки Makefile.PL нужен класс cpan.bbclass;
для модулей, применяющих систему сборки на основе Build.PL, нужен класс cpan_build.bbclass.

В обоих случаях наследуется класс cpan-base для базовой поддержки Perl.

6.24. `cross.bbclass`

Класс cross обеспечивает поддержку заданий для сборки инструментов кросс-компиляции.

6.25. `cross-canadian.bbclass`

Класс cross-canadian обеспечивает поддержку заданий, собирающих инструменты канадской кросс-компиляции для SDK (см раздел Cross-Development Toolchain Generation [1]).

6.26. `crosssdk.bbclass`

Класс crosssdk обеспечивает поддержку заданий, собирающих инструменты кросс-компиляции для сборки SDK (см раздел Cross-Development Toolchain Generation [1]).

6.27. `debian.bbclass`

Класс debian переименовывает выходные пакеты в соответствии с политикой именования Debian (т. е. glibc становится libc6, а glibc-devel — libc6-dev.). Переименования включает имя библиотеки и версию как часть имени пакета. Если задание создает пакеты для нескольких библиотек (файлы общих объектов типа .so), следует использовать в задании переменную LEAD_SONAME для указания библиотеки, к которой применяется схема именования.

6.28. `deploy.bbclass`

Класс deploy обслуживает развертывание файлов в каталоге DEPLOY_DIR_IMAGE. Основной задачей класса является ускорение этапа развертывания за счет использования общего состояния. Наследующие этот класс задания должны определять свою функцию do_deploy для копирования файлов, разворачиваемых в DEPLOYDIRи использовать addtask для добавления этой задачи в нужное место (обычно после задачи do_compile или do_install). Затем класс обеспечивает размещение файлов из DEPLOYDIR в DEPLOY_DIR_IMAGE.

6.29. `devshell.bbclass`

Класс devshell добавляет задачу do_devshell. Включение этого класса определяется политикой дистрибутива. Использование класса описано в разделе Using a Development Shell [2].

6.30. `devupstream.bbclass`

Класс devupstream использует BBCLASSEXTEND для добавления варианта задания с выборкой из другого URI (например, Git) вместо архива.

     BBCLASSEXTEND = "devupstream:target"
     SRC_URI_class-devupstream = "git://git.example.com/example"
     SRCREV_class-devupstream = "abcd1234"

Добавление этих операторов в задание создаст вариант с DEFAULT_PREFERENCE = «-1», поэтому нужно будет выбрать используемый вариант задания. Можно внести нужные изменения путем переопределения class-devupstream.

     DEPENDS_append_class-devupstream = " gperf-native"

     do_configure_prepend_class-devupstream() {
        touch ${S}/README
     }

В настоящее время класс поддерживает лишь создание development-вариантов заданий для целевых платформ (не native или nativesdk). Синтаксис BBCLASSEXTEND (devupstream:target) обеспечивает поддержку вариантов native и nativesdk,которая будет добавлена в новых выпусках.

Поддержка других систем контроля версий (например, Subversion) ограничена зависимостями автоматической сборки BitBake (subversion-native).

6.31. `distro_features_check.bbclass`

Класс distro_features_check позволяет отдельным заданиям проверять требуемые и конфликтующие свойства DISTRO_FEATURES. Этот класс обеспечивает поддержку переменных REQUIRED_DISTRO_FEATURES и CONFLICT_DISTRO_FEATURES. Если какое-либо из условий, указанных в задании с помощью этих переменных не выполняется, задание будет пропущено.

6.32. `distutils*.bbclass`

Классы distutils* поддерживают задания для расширений Python версий 2.x. Обычно эти задания нужны лишь для указания архива исходного кода и наследования подходящего класса. При сборке возможны 3 метода в зависимости от выбора автора модуля.

Расширения с автоматизированной сборкой, требующие Autotools и классы на основе distutils в задании.
Расширения со сборкой на основе distutils, требующие класс distutils в своих заданиях.
Расширения со сборкой на основе setuptools,требующие классsetuptools в своих заданиях.

Некоторым классам distutils* нужен класс distutils-common-base для поддержки Python2.

6.33. `distutils3*.bbclass`

Классы distutils3* поддерживают задания для расширений Python версий 3.x. Обычно эти задания нужны лишь для указания архива исходного кода и наследования подходящего класса. При сборке возможны 3 метода в зависимости от выбора автора модуля.

Расширения с автоматизированной сборкой, требующие Autotools и классы на основе distutils в задании.
Расширения со сборкой на основе distutils, требующие класс distutils в своих заданиях.
Расширения со сборкой на основе setuptools3,требующие классsetuptools3 в своих заданиях.

Классы distutils3* наследуют соответствующий класс distutils* или реплицируют его с использованием Python3 (например, distutils3-base наследует класс distutils-common-base, который повторяет distutils-base,но наследует python3native вместо pythonnative).

6.34. `externalsrc.bbclass`

Класс externalsrc поддерживает сборку программ из исходных кодов, находящихся за пределами системы сборки OE. Сборка из внешних источников исключает обычную выборку, распаковку и применение правок. По умолчанию система сборки OE использует переменные S и B для нахождения распакованных исходных кодов и сборки. При наследовании заданием класса externalsrc переменные EXTERNALSRC и EXTERNALSRC_BUILD в конечном итоге задают S и B.

По умолчанию этот класс предполагает, что исходный код поддерживает сборку с использованием переменной B для указания каталога, куда система сборки OE будет помещать созданные объекты. По умолчанию каталог B отделен от дерева исходных кодов (S) и задается в форме ${WORKDIR}/${BPN}/{PV}/.

Дополнительная информация о классе externalsrc приведена в комментариях файла meta/classes/externalsrc.bbclass в дереве исходного кода, а использование класса описано в разделе Building Software from an External Source [2].

6.35. `extrausers.bbclass`

Класс extrausers позволяет применить дополнительные конфигурации пользователей и групп на уровне образа. Наследование этого класса задается глобально или в задании для образа разрешается выполнение дополнительных пользовательских и групповых операций с использованием переменной EXTRA_USERS_PARAMS.

Пользовательские и групповые операции, добавленные с использованием extrausers,не привязаны к конкретным заданиям за пределами задания для образа. Таким образом, операции могут выполняться для образа в целом. Класс useradd добавляет конфигурацию пользователей и групп к конкретному заданию.

Ниже приведен пример использования класса в задании для образа.

     inherit extrausers
     EXTRA_USERS_PARAMS = "\
         useradd -p '' tester; \
         groupadd developers; \
         userdel nobody; \
         groupdel -g video; \
         groupmod -g 1020 developers; \
         usermod -s /bin/sh tester; \
         "

Следующий пример добавляет пользователей tester-jim и tester-sue, а также назначает для них пароль tester01.

     inherit extrausers
     EXTRA_USERS_PARAMS = "\
         useradd -P tester01 tester-jim; \
         useradd -P tester01 tester-sue; \
         "

Еще один пример устанавливает для пользователя root пароль 1876*18:

     inherit extrausers
     EXTRA_USERS_PARAMS = "\
         usermod -P 1876*18 root; \
         "

6.36. `fontcache.bbclass`

Класс fontcache генерирует нужные сценарии пост-установки и пост-удаления (postinst и postrm) для шрифтовых пакетов. Эти сценарии вызывают команду fc-cache (часть Fontconfig) для добавления шрифтов в кэш информации. Поскольку кэш-файлы зависят от архитектуры, fc-cache запускается с использованием QEMU, если сценарии postinst нужно запускать на сборочном хосте при создании образа. Если шрифты устанавливаются не в основном пакете задания, нужно указать в переменной FONT_PACKAGES пакеты, содержащие шрифты.

6.37. `fs-uuid.bbclass`

Класс fs-uuid извлекает UUID из значения ${ROOTFS}, которое должно присутствовать в момент вызова функции. Класс работает только с файловыми системами ext и зависит от tune2fs.

6.38. `gconf.bbclass`

Класс gconf обеспечивает базовую функциональность для заданий, которым нужно устанавливать схемы GConf. Схемы будут помещаться в отдельный пакет (${PN}-gconf), создаваемый автоматически при наследовании этого класса. Этот пакет использует подходящие сценарии пост-установки и пост-удаления (postinst и postrm) для регистрации и дерегистрации схем в целевом образе.

6.39. `gettext.bbclass`

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

6.40. `gnome.bbclass`

Класс gnome поддерживает задания, собирающие программы из стека GNOME. Этот класс наследует классы gnomebase, gtk-icon-cache, gconf и mime,а также отключает самоанализGobject, когда это приемлемо.

6.41. `gnomebase.bbclass`

Класс gnomebase является базовым для заданий, собирающих программы из стека GNOME. Класс устанавливает SRC_URI для загрузки исходного кода с зеркал GNOME, а также расширяет переменную FILES типовыми путями установки GNOME.

6.42. `gobject-introspection.bbclass`

Обеспечивает поддержку заданий, собирающих программы с самоанализом GObject. Эта функциональность доступна только при наличии свойства gobject-introspection-data в DISTRO_FEATURES, а также qemu-usermode в MACHINE_FEATURES.

Эта функциональность по умолчанию включена и в случае неприменимости ее следует отключать в переменной DISTRO_FEATURES_BACKFILL_CONSIDERED или MACHINE_FEATURES_BACKFILL_CONSIDERED.

6.43. `grub-efi.bbclass`

Класс grub-efi задает относящиеся к режиму grub-efi функции для сборки загружаемых образов. Класс поддерживает перечисленные ниже переменные.

INITRD - указывает список образов файловых систем для конкатенации и применения в качестве стартового RAM-диска (initrd). Необязательна.
ROOTFS - указывает образ файловой системы для включения в качестве корневой. Необязательна.
GRUB_GFXSERIAL - значение 1 задает графический режим и консоль serial.
LABELS - список целей для автоматической настройки конфигурации.
APPEND — список переопределения добавленных строк для каждой метки LABEL.
GRUB_OPTS - дополнительные опции конфигурации, разделенные символом ;. Необязательна.
GRUB_TIMEOUT - время ожидания перед выбором заданной по умолчанию метки. Необязательна.

6.44. `gsettings.bbclass`

Класс gsettings обеспечивает базовую функциональность для заданий, которым требуется устанавливать схемы GSettings (glib). Схемы предполагаются частью основного пакета. Для регистрации и исключения схем из целевого образа добавляются соответствующие сценарии пост-установки и пост-удаления (postinst/postrm).

6.45. `gtk-doc.bbclass`

Класс gtk-doc является вспомогательным для извлечения подходящих зависимостей gtk-doc и отключения gtk-doc.

6.46. `gtk-icon-cache.bbclass`

Класс gtk-icon-cache генерирует соответствующие сценарии пост-установки и пост-удаления (postinst/postrm) для пакетов, использующих GTK+ и пиктограммы установки. Эти сценарии вызывают gtk-update-icon-cache для добавления шрифтов в кэш пиктограмм GTK+. Поскольку кэш-файлы зависят от архитектуры, класс gtk-update-icon-cache работает на основе QEMU, если сценарии пост-установки нужно запускать на сборочном хосте в процессе создания образа.

6.47. `gtk-immodules-cache.bbclass`

Класс gtk-immodules-cache генерирует соответствующие сценарии пост-установки и пост-удаления (postinst/postrm) для пакетов, использующих методы ввода GTK+ для виртуальной клавиатуры. Эти сценарии могут вызывать gtk-update-icon-cache для добавления в кэш методов ввода. Поскольку кэш-файлы зависят от архитектуры, класс gtk-update-icon-cache работает на основе QEMU, если сценарии пост-установки нужно запускать на сборочном хосте в процессе создания образа.

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

6.48. `gzipnative.bbclass`

Класс gzipnative включает использование естественных версий gzip и pigz вместо версий, доступных на хосте сборки.

6.49. `icecc.bbclass`

Класс icecc поддерживает программу Icecream, упрощающую компиляцию заданий и распределяющую их между удаленными машинами. Класс представляет каталоги с символьными ссылками gcc и g++ на icecc как для естественных, так и для кросс-компиляторов. В зависимости от конфигурации или компиляции система сборки OE добавляет каталоги в начало переменной PATH, а затем использует переменные ICECC_CXX и ICEC_CC, которые указывают на компиляторы g++ и gcc, соответственно. Для кросс-компиляторов класс создает файл tar.gz с инструментарием YP и устанавливает в переменной ICECC_VERSION используемую
версию компилятора, используемого для кросс-разработки. Класс обрабатывает эти три этапа компиляции (native, cross-kernel, target) и создает требуемую среду в файле tar.gz для использования удаленными машинами. Класс также поддерживает генерацию SDK.

Если переменная ICECC_PATH не задана в файле local.conf, класс пытается найти двоичный файл icecc для использования. Если переменная ICECC_ENV_EXEC установлена в local.conf, ей следует указывать пользовательский сценарий icecc-create-env. Если переменная не указывает такой сценарий, система сборки использует принятый по умолчанию из задания icecc-create-env-native.bb. Этот сценарий изменен по сравнению с распространяемым в icecc.

Если не нужно применять распределенную компиляцию Icecream к определенным заданиям или классам, можно поместить их в «черный список» с помощью переменных ICECC_USER_PACKAGE_BL и ICECC_USER_CLASS_BL в файле local.conf. Это приведет к локальной обработке таких заданий и классов системой сборки OE.

Кроме того, можно указать с помощью переменной ICECC_USER_PACKAGE_WL в local.conf задания для форсированного применения icecc в заданиях с пустой переменной PARALLEL_MAKE.

Наследование класса icecc меняет все подписи sstate, поэтому при наличии в команде разработки выделенной системы сборки, которая заполняет STATE_MIRRORS и желании многократно использовать sstate из STATE_MIRRORS, наследовать класс icecc должны все разработчики или никто из них.

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

     INHERIT_DISTRO_append = " icecc"
     ICECC_DISABLED ??= "1"

Такой подход обеспечивает использование всеми одних подписей, но требует от каждого, кто хочет применять Icecream включить это свойство в файле local.conf с помощью строки ICECC_DISABLED = «».

6.50. `image.bbclass`

Класс image помогает создавать образы в разных форматах. Сначала создается корневая файловая система с использованием одного из файлов rootfs*.bbclass (в зависимости от используемого формата пакетов), затем создается один или несколько файлов с образами. Типы образов определяются переменной IMAGE_FSTYPES, а список пакетов, включаемых в образ, задает переменная IMAGE_INSTALL.

Настройка образов описана в разделе Customizing Images [2], а их создание — в разделе Images [1].

6.51. `image-buildinfo.bbclass`

Класс image-buildinfo записывает информацию в каталог /etc/build целевой файловой системы.

6.52. `image_types.bbclass`

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

По умолчанию класс image автоматически включает image_types. Класс image использует переменную IMGCLASSES, как показано ниже.

IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
IMGCLASSES += "image_types_wic"
IMGCLASSES += "rootfs-postcommands"
IMGCLASSES += "image-postinst-intercepts"
inherit ${IMGCLASSES}

Класс image_types также обслуживает преобразование и сжатие образов.

Для сборки образа VMware VMDK нужно добавить wic.vmdk в переменную IMAGE_FSTYPES. Похожая операция выполняется для создания образов vdi³ и qcow2⁴.

6.53. `image-live.bbclass`

Этот класс контролирует сборку «живых» (live) образов (HDDIMG и ISO), содержащих syslinux для унаследованной загрузки, а также загрузчик (bootloader), заданный в EFI_PROVIDER, если MACHINE_FEATURES содержит efi. Обычно этот класс напрямую не используется, а добавляется значение live в IMAGE_FSTYPES.

6.54. `image-mklibs.bbclass`

Класс image-mklibs разрешает использование в задаче do_rootfs утилиты mklibs, оптимизирующей размер библиотек в образе. По умолчанию класс включается в файле local.conf.template с использованием переменной USER_CLASSES.

     USER_CLASSES ?= "buildstats image-mklibs image-prelink"

6.55. `image-prelink.bbclass`

Класс image-mklibs разрешает использование в задаче do_rootfs утилиты prelink, оптимизирующей динамическую компоновку общих библиотек для снижения времени запуска исполняемых файлов. По умолчанию класс включается в файле local.conf.template с использованием переменной USER_CLASSES.

     USER_CLASSES ?= "buildstats image-mklibs image-prelink"

6.56. `insane.bbclass`

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

Можно настроить проверку работоспособности с выдачей при отказах предупреждений или сообщений об ошибках. Обычно при первом отказе конкретного теста выдается предупреждение, а последующие считаются ошибками, когда метаданные известны и корректны. Глава 10. Ошибки и предупреждения тестов QA описывает все предупреждения и сообщения об ошибках, которые могут выдаваться в принятой по умолчанию конфигурации.

Переменные WARN_QA и ERROR_QA управляют поведением при проверке на глобальном уровне (уровень конфигурации дистрибутива). Можно пропустить одну или несколько проверок, указав их в переменной INSANE_SKIP. Например, для пропуска проверки символьных ссылок для файлов .so в задании для основного пакета добавляется INSANE_SKIP_${PN} += «dev-so». Следует помнить об переопределениях имен пакетов (в примере ${PN}).

Проверки QA служат для обнаружения имеющихся и возможных проблем в упакованном выводе. Поэтому при отключении проверок следует соблюдать осторожность.

Ниже приведен список всех тестов, которые можно указывать в переменных WARN_QA и ERROR_QA.

already-stripped

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

arch

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

buildpaths

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

build-deps

Проверяет соответствие зависимостей при сборке, заданных в DEPENDS (кроме RDEPENDS), или зависимостей на уровне задачи зависимостям, заданным для работы (runtime). Такая проверка полезна, в частности, для определения моментов обнаружения и добавления runtime-зависимостей в процессе упаковки. Если в метаданных не задано явных зависимостей, на этапе упаковки будет поздно обеспечивать создание зависимостей и процесс может установки пакета в образ завершиться ошибкой при выполнении задачи do_rootfs, поскольку обнаруженные автоматически зависимости не выполнены. Примером может служить автоматическое добавление зависимостей классом update-rc.d в пакете initscripts-functions для пакетов, которые устанавливают сценарии инициализации, ссылающиеся на файл /etc/init.d/functions. Заданию следует включать явные RDEPENDS для пакетов от initscripts-functions, чтобы система сборки OE могла гарантировать, что задание initscripts действительно собрано и пакет initscripts-functions доступен.

compile-host-path

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

debug-deps

Проверяет независимость всех пакетов, кроме -dbg, от отладочных пакетов -dbg (зависимость может привести к ошибкам упаковки).

debug-files

Проверяет наличие в каталогах .debug посторонних (не относящихся к пакетам -dbg) файлов. Все отладочные файлы должны находиться в пакетах -dbg.

dep-cmp

Проверяет наличие недействительных операторов сравнения версий в зависимостях между пакетами при работе (т. е. в переменных RDEPENDS, RRECOMMENDS, RSUGGESTS, RPROVIDES, RREPLACES, RCONFLICTS). Некорректное сравнение может вызывать отказы и нежелательное поведение при передаче менеджеру пакетов.

desktop

Запускает программу desktop-file-validate для проверки всех файлов .desktop на предмет соответствия их содержимого спецификации файлов .desktop.

dev-deps

Проверяет независимость всех пакетов, кроме -dev и -staticdev от пакетов -dev, для предотвращения ошибок упаковки.

dev-so

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

file-rdeps

Проверяет выполнение зависимостей на уровне файлов, идентифицированных системой сборки OE. Например, сценарий оболочки может начинаться со строки #!/bin/bash, которая будет транслироваться в зависимость от файла /bin/bash. Из трех менеджеров пакетов, поддерживаемых системой сборки OE, лишь RPM напрямую обрабатывает зависимости на уровне файлов, автоматически преобразуя их в зависимости от пакетов, содержащих нужные файлы. Однако отсутствие такой функциональности в других менеджерах пакетов не означает необходимости преобразования зависимостей. Эта проверка QA пытается обеспечить наличие явно созданных RDEPENDS для обработки всех зависимостей на уровне файлов, найденных в файлах пакета.

files-invalid

Проверяет наличие в переменной FILES наличие недопустимых значений с //.

host-user-contaminated

Проверяет, что ни один из созданных заданием пакетов не содержит файлов за пределами /home с идентификаторами пользователя и группы, соответствующими пользователю, применяющему BitBake. Наличие таких файлов обычно означает их установку с некорректными UID/GID, поскольку идентификаторы на целевой платформе не зависят от идентификаторов на хосте. Дополнительная информация приведена в описании задачи do_install task.

incompatible-license

Сообщает о пакетах, исключенных из сборки по причине наличия лицензии, указанной в INCOMPATIBLE_LICENSE.

install-host-path

Проверяет журнал do_install для указания использования путей к местоположению на сборочном хосте. Использование таких путей может приводить в «загрязнению» хоста выводом сборки.

installed-vs-shipped

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

invalid-chars

Проверяет, что переменные метаданных DESCRIPTION, SUMMARY, LICENSE и SECTION в задании не содержат символов, отличных от UTF-8. Некоторые менеджеры пакетов не поддерживают такие символы.

invalid-packageconfig

Проверяет отсутствие не определенных свойств в переменной PACKAGECONFIG. Например, любых имен foo, для которых не существует форма PACKAGECONFIG[foo] = «…»

la

Проверяет файлы .la на предмет наличия в путях TMPDIR. Любой файл .la в таком пути является некорректным, поскольку libtool добавляет корректный префикс sysroot при автоматическом использовании самих файлов.

ldflags

Обеспечивает компоновку двоичных файлов с опциями LDFLAGS, предоставленными системой сборки. Если этот тест не проходит, следует проверить передачу переменной LDFLAGS команде компоновщика.

libdir

Проверяет установку библиотек в некорректные (возможно, жестко заданные) пути. Например, этот тест будет находить задание, которое устанавливает /lib/bar.so при ${base_libdir} lib32. Другим примером является задание, устанавливающее /usr/lib64/foo.so при ${libdir} /usr/lib.

libexec

Проверяет наличие в пакете файлов в /usr/libexec. Эта проверка не выполняется, если переменная libexecdir явно указывает /usr/libexec.

packages-list

Проверяет многократное включение пакета в переменную PACKAGES, что может вызывать проблемы при подготовке пакетов.

perm-config

Указывает строки с непригодным форматом в fs-perms.txt.

perm-line

Указывает строки с непригодным форматом в fs-perms.txt.

perm-link

Указывает строки в файле fs-perms.txt задающие link, когда указанная цель уже существует.

perms

В настоящее время не используется (резерв).

pkgconfig

Проверяет файлы .pc на предмет наличия путей TMPDIR/WORKDIR. Любой файл .pc file, содержащий такие пути, является некорректным, поскольку pkg-config добавляет корректный префикс sysroot при обращении к файлам.

pkgname

Проверяет отсутствие у всех пакетов из PACKAGES имен с недопустимыми символами (кроме 0-9, a-z, ., +, и -).

pkgv-undefined

Проверяет, установлена ли переменная PKGV во время выполнения задачи do_package.

pkgvarcheck

Проверяет переменные RDEPENDS, RRECOMMENDS, RSUGGESTS, RCONFLICTS, RPROVIDES, RREPLACES, FILES, ALLOW_EMPTY, pkg_preinst, pkg_postinst, pkg_prerm и pkg_postrm на предмет установок, не являющихся специфическими для пакета. Использование этих переменных без связанного с пакетом суффикса может приводить к неоправданному усложнению зависимостей других пакетов в том же задании и другим побочным эффектам.

pn-overrides

Проверяет отсутствие значения имени (PN) задания в переменной OVERRIDES. Если задание названо так, что его значение PN соответствует имеющемуся в OVERRIDES (например, PN совпадает с MACHINE или DISTRO), это может приводить к неожиданным последствиям, например, назначения вида FILES_${PN} = «xyz» фактически превратятся в FILES = «xyz».

rpaths

Проверяет rpaths в исполняемых файлах на предмет наличия путей системы сборки, таких как TMPDIR. При наличии таких путей будут переданы неверные опции -rpath в команды компоновщика и в исполняемых файлах могут возникнуть проблемы безопасности.

split-strip

Сообщает об отказах при выделении или удалении отладочных символов из исполняемых файлов.

staticdev

Проверяет наличие статических библиотек (*.a) а пакетах, не являющихся staticdev.

symlink-to-sysroot

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

textrel

Проверяет наличие в исполняемых файлах ELF перемещений (relocation) в их разделах .text, что может влиять на производительность работы. При наличии таких перемещений система сборки выдает сообщение, описанное в параграфе 10.2. Ошибки и предупреждения.

useless-rpaths

Проверяет в исполняемых файлах пути загрузки динамических библиотек (rpath), которые по умолчанию на стандартных системах ищет компоновщик (например, /lib и /usr/lib). Хотя эти пути не будут вызывать проблем, они не требуются и будут занимать пространство.

var-undefined

Сообщает о важных для подготовки пакетов переменных (WORKDIR, DEPLOY_DIR, D, PN, PKGD), которые не определены во время задачи do_package.

version-going-backwards

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

xorg-driver-abi

Проверяет во всех пакетах с драйверами Xorg наличие зависимости ABI. Задание xserver-xorg обеспечивает имена драйверов ABI. Все драйверы должны зависеть от версии ABI, с которой они собраны. Задания для драйверов, включающие файл xorg-driver-input.inc или xorg-driver-video.inc, будут получать версию автоматически. Поэтому нужно лишь явно добавить зависимости для заданий.

6.57. `insserv.bbclass`

Класс insserv использует утилиту insserv для обновления других символьных ссылок в /etc/rc?.d/ внутри образа на основе зависимостей, заданных заголовками LSB в сценариях init.d.

6.58. `kernel.bbclass`

Класс kernel отвечает за сборку ядер Linux и содержит код для сборки деревьев ядра. Нужные заголовки собираются в каталоге STAGING_KERNEL_DIR, чтобы можно было собрать внешние модули с помощью класса module.

Это означает, что каждый собираемый модуль ядра пакуется отдельно и создаются зависимости между модулями путем анализа modinfo. Если требуются все модули, установка пакета kernel-modules обеспечивает инсталляцию всех пакетов с модулями и другими пакетами ядра, такими как kernel-vmlinux.

Логика класса kernel позволяет встраивать образ файловой системы initramfs при сборке образа ядра (см. раздел Building an Initial RAM Filesystem (initramfs) Image [2]).

Классы kernel и module используют внутри себя другие классы, включая kernel-arch, module-base и linux-kernel-base.

6.59. `kernel-arch.bbclass`

Класс kernel-arch устанавливает переменную окружения ARCH для компиляции ядра Linux (включая модули).

6.60. `kernel-devicetree.bbclass`

Класс kernel-devicetree, наследующий kernel, поддерживает генерацию дерева устройств.

6.61. `kernel-fitimage.bbclass`

Класс kernel-fitimage обеспечивает поддержку образов zImage.

6.62. `kernel-grub.bbclass`

Класс kernel-grub обновляет область и меню загрузки с ядром в качестве приоритетного механизма загрузки при установке RPM обновления ядра на развернутой платформе.

6.63. `kernel-module-split.bbclass`

Класс kernel-module-split обеспечивает базовые функции для разделения модулей ядра Linux в отдельные пакеты.

6.64. `kernel-uboot.bbclass`

Класс kernel-uboot поддерживает сборку образов из репозиториев ядра в стиле vmlinux.

6.65. `kernel-uimage.bbclass`

Класс kernel-uimage поддерживает упаковку uImage.

6.66. `kernel-yocto.bbclass`

Класс kernel-yocto обеспечивает базовую функциональность для сборки из репозиториев со стилем ядра linux-yocto.

6.67. `kernelsrc.bbclass`

Класс kernelsrc устанавливает исходные коды и версию ядра Linux.

6.68. `lib_package.bbclass`

Класс lib_package поддерживает задания, собирающие библиотеки и создающие двоичные исполняемые файлы, которые по умолчанию не следует устанавливать вместе с библиотекой. Эти исполняемые двоичные файлы добавляются в отдельный пакет ${PN}-bin.

6.69. `libc*.bbclass`

Классы libc* поддерживают задания, собирающие пакеты с libc:

libc-common обеспечивает базовую поддержу сборки с использованием libc;
libc-package обеспечивает поддержу сборки с использованием glibc и eglibc.

6.70. `license.bbclass`

Класс license обеспечивает создание манифеста лицензий и исключение лицензий. Класс включен по умолчанию через принятое по умолчанию значение переменной INHERIT_DISTRO.

6.71. `linux-kernel-base.bbclass`

Класс linux-kernel-base обеспечивает базовую функциональность для заданий, которые собираются из дерева исходных кодов ядра Linux, не включая сборку самого ядра. Например, задание perf наследует этот класс.

6.72. `linuxloader.bbclass`

Обеспечивает функцию linuxloader(), сообщающую динамический загрузчик/компоновщик, обеспечиваемый платформой. Значение функции используется множеством других классов.

6.73. `logging.bbclass`

Обеспечивает стандартные функции оболочки, используемые для записи в журнал сообщений BitBake с различными уровнями важности (bbplain, bbnote, bbwarn, bberror, bbfatal, bbdebug). Класс включен по умолчанию, поскольку наследуется классом base.

6.74. `meta.bbclass`

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

6.75. `metadata_scm.bbclass`

Класс metadata_scm обеспечивает функциональность для запроса ветви и выпуска репозитория SCM. Класс base применяет этот класс для печати выпуска каждого задания перед его сборкой. Класс metadata_scm включен по умолчанию, поскольку наследуется классом base.

6.76. `migrate_localcount.bbclass`

Класс migrate_localcount проверяет и инкрементирует данные localcount в задании.

6.77. `mime.bbclass`

Класс mime создает нужные сценарии пост-установки и пост-удаления (postinst/postrm) для пакетов, устанавливающих файлы типов MIME. Эти сценарии вызывают update-mime-database для добавления типов MIME в общую базу данных.

6.78. `mirrors.bbclass`

Класс mirrors организует некоторые стандартные записи MIRRORS для зеркал исходного кода, которые обеспечивают резервные пути при недоступности репозитория, заданного в SRC_URI. Класс включен по умолчанию, поскольку наследуется классом base.

6.79. `module.bbclass`

Класс module обеспечивает поддержку сборки внешних (out-of-tree) модулей ядра Linux. Этот класс наследует классы module-base и kernel-module-split, а также реализует задачи do_compile и do_install. Класс обеспечивает все, что нужно для сборки и упаковки модулей ядра.

Базовая информация о сборке внешних модулей ядра приведена в разделе Incorporating Out-of-Tree Modules [3].

6.80. `module-base.bbclass`

Класс module-base обеспечивает базовые функции сборки модулей ядра Linux. Обычно задание для сборки программы, включающей один или несколько модулей ядра и имеющей свои средства сборки, наследует этот класс , а не класс module.

6.81. `multilib*.bbclass`

Класс multilib* обеспечивает поддержку сборки библиотек с оптимизацией для разных платформ и для разной архитектуры с установкой всех библиотек в один образ. Информация о работе с множеством библиотек приведена в разделе Combining Multiple Versions of Library Files into One Image [2].

6.82. `native.bbclass`

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

Задание myrecipe-native.bb, наследующее класс native. В этом случае нужно указать оператор inherit для класса native в задании после всех других операторов inherit, чтобы класс native наследовался последним. Имя для такого задания должно иметь форму myrecipe-native.bb, поскольку другие формы именования могут создавать конфликты с имеющимся кодом, который зависит от согласованного именования.
Задание для целевой платформы, содержащее строку BBCLASSEXTEND = «native». Внутри этого задания указываются переопределения _class-native и _class-target для уточнения функциональности, относящейся к заданию для хоста или целевой платформы.

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

6.83. `nativesdk.bbclass`

Класс nativesdk обеспечивает базовую функциональность для заданий, собирающих инструменты, которые будут работать как часть SDK (т. е. на SDKMACHINE). Задание можно создать двумя разными способами.

Задание nativesdk-myrecipe.bb, наследующее класс nativesdk. В этом случае нужно указать оператор inherit для класса nativesdk в задании после всех других операторов inherit, чтобы этот класс наследовался последним. Имя для такого задания должно иметь форму nativesdk-myrecipe.bb, поскольку другие формы именования могут создавать конфликты с имеющимся кодом, который зависит от согласованного именования.
Задание, содержащее строку BBCLASSEXTEND = «nativesdk». Внутри этого задания указываются переопределения _class-nativesdk и _class-target для уточнения функциональности, относящейся к заданию для SDK или целевой платформы.

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

6.84. `nopackages.bbclass`

Отключает подготовку пакетов для заданий и классов, где пакеты не требуются.

6.85. `npm.bbclass`

Обеспечивает поддержку сборки программ Node.js из NPM ⁶. В настоящее время задания, наследующие этот класс, должны применять сборщик npm:// для установки зависимостей и автоматической подготовки пакетов. Работа с пакетами NPM описана в разделе Creating Node Package Manager (NPM) Packages [2].

6.86. `oelint.bbclass`

Класс oelint задает устаревший инструмент проверки lint из meta/classes в каталоге исходных кодов. Имеется много классов, которые могут быть полезны в OE-Core, но в реальности никогда не применяются на этом уровне. Класс oelint является одним из таких классов. Однако информация о нем может снизить число разных версий похожих классов на разных уровнях.

6.87. `own-mirrors.bbclass`

Класс own-mirrors упрощает настройку своих зеркал в переменной PREMIRRORS, в соответствии с которой выполняется выборка до обращения кSRC_URI в каждом задании. Для использования этого класса его нужно наследовать глобально и задать переменную SOURCE_MIRROR_URL, как показано ниже.

     INHERIT += "own-mirrors"
     SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"

В переменной SOURCE_MIRROR_URL можно указать лишь один идентификатор URL.

6.88. `package.bbclass`

Этот класс поддерживает базовую функциональность создания пакетов из вывода сборки. Код, относящийся к конкретным типам упаковки, содержится в классах package_deb, package_rpm, package_ipk, and package_tar. Последний из этих классов применять не рекомендуется.

Список форматов упаковки можно задать с помощью переменной PACKAGE_CLASSES в файле conf/local.conf каталога сборки. Переменная может включать несколько типов упаковки. Поскольку образы создаются из пакетов, класс упаковки требуется задать для создания образа. Система сборки будет выбирать из списка указанный первым класс.

При необязательной настройке репозитория (источника пакетов) на хосте разработки, который может использоваться DNF, можно устанавливать пакеты из этого источника при работе образа на целевой платформе (см. раздел Using Runtime Package Management [2]).

Выбранный класс для конкретного пакета может влиять на производительность сборки и требуемое пространство. В общем случае сборка пакетов с использованием IPK примерно на треть быстрее сборки с использованием RPM. Это сравнение учитывает полную сборку пакета со всеми зависимостями, собранными заранее. Причина этого заключается в том, что менеджер пакетов RPM создает и обрабатывает больше метаданных, нежели менеджер IPK. Поэтому для небольших систем целесообразно выбрать для PACKAGE_CLASSES значение «package_ipk».

При выборе менеджера пакетов следует рассмотреть использование RPM с учетом отмеченного ниже.

RPM обеспечивает больше возможностей по сравнению с IPK за счет обработки большего объема метаданных. Например, метаданные включают типы отдельных файлов, контрольные суммы, поддержку «разбросанных» файлов, обнаружение и разрешение конфликтов в системах Multilib, обновление в стиле ACID, и возможность перепаковки для откатов назад.
Для небольших систем дополнительное пространство, занятое Berkeley Database и объем метаданных RPM могут влиять на возможности обновления.

Дополнительные сведения о влиянии класса package приведены в рассылках https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html и https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html

6.89. `package_deb.bbclass`

Класс package_deb поддерживает создание пакетов в формате Debian (.deb), обеспечивая их запись в каталог ${DEPLOY_DIR_DEB}.Этот класс наследуетклассpackage и включается переменной PACKAGE_CLASSES в local.conf.

6.90. `package_ipk.bbclass`

Класс package_ipk поддерживает создание пакетов в формате IPK (.ipk), обеспечивая их запись в каталог ${DEPLOY_DIR_IPK}. Этот класс наследуетклассpackage и включается переменной PACKAGE_CLASSES в local.conf.

6.91. `package_rpm.bbclass`

Класс package_rpm поддерживает создание пакетов в формате RPM (.rpm), обеспечивая их запись в каталог ${DEPLOY_DIR_RPM}. Этот класс наследуетклассpackage и включается переменной PACKAGE_CLASSES в local.conf.

6.92. `package_tar.bbclass`

Класс package_tar поддерживает создание пакетов в форме архивов (tarball), обеспечивая их запись в каталог ${DEPLOY_DIR_TAR}. Этот класс наследуетклассpackage и включается переменной PACKAGE_CLASSES в local.conf.

Класс package_tar нельзя указывать первым в переменной PACKAGE_CLASSES,для образов и SDK должен применяться формат.deb, .ipkили .rpm.

6.93. `packagedata.bbclass`

Класс packagedata обеспечивает базовую функциональность для чтения файлов pkgdata из переменной PKGDATA_DIR. Эти файлы содержат информацию о каждом пакете, создаваемом системой сборки OE.

Этот класс включен по умолчанию, поскольку он наследуется классом package.

6.94. `packagegroup.bbclass`

Класс packagegroup устанавливает принятые по умолчанию значения, пригодные для заданий групп пакетов (PACKAGES, PACKAGE_ARCH, ALLOW_EMPTYи т. п.). Настоятельно рекомендуется наследовать этот класс всем заданиям для групп. Использование класса описано в разделе Customizing Images Using Custom Package Groups [2].

Ранее этот класс носил имя task.

6.95. `patch.bbclass`

Класс patch обеспечивает функциональность наложения исправлений в задаче do_patch. Класс включен по умолчанию, поскольку наследуется классом base.

6.96. `perlnative.bbclass`

Класс perlnative поддерживает использование естественной версии Perl, созданной системой сборки вместо версии, предоставляемой сборочным хостом.

6.97. `pixbufcache.bbclass`

Класс pixbufcache создает нужные сценарии пост-установки и пост-удаления (postinst/postrm) для пакетов, устанавливающих загрузчики pixbuf, которые применяются с gdk-pixbuf. Эти сценарии вызывают update_pixbuf_cache для добавления загрузчиков pixbuf в кэш. Поскольку файлы кэширования зависят от архитектуры, update_pixbuf_cache запускается с использованием QEMU если сценарии пост-установки нужно запускать на сборочном хосте в процессе создания образа. Если загрузчики pixbuf устанавливаются не в основном пакете, следует установить переменную PIXBUF_PACKAGES для указания этих пакетов.

6.98. `pkgconfig.bbclass`

Класс pkgconfig обеспечивает стандартный способ получения информации о заголовках и библиотеках с помощью pkg-config. Этот класс нацелен на интеграцию pkg-config с использующими программу библиотеками. В процессе подготовки BitBake устанавливает данные pkg-config в каталог sysroots/. За счет использования функциональности sysroot в пакете pkg-config классу pkgconfig больше не требуются манипуляции с файлами.

6.99. `populate_sdk.bbclass`

Класс populate_sdk обеспечивает поддержку заданий, содержащих только SDK. Описание сборки инструментов кросс-разработки с применением задачи do_populate_sdk приведено в разделе Building an SDK Installer [7].

6.100. `populate_sdk_*.bbclass`

Классы populate_sdk_* поддерживают создание SDK:

populate_sdk_base — базовый класс для создания SDK со всеми менеджерами пакетов (DEB, RPM, opkg);
populate_sdk_deb - создание SDK с помощью менеджера пакетов Debian;
populate_sdk_rpm - создание SDK с помощью менеджера пакетов RPM;
populate_sdk_ipk - создание SDK с помощью менеджера пакетов opkg (IPK);
populate_sdk_ext - создание расширяемых SDK с помощью со всеми менеджерами пакетов.

Класс populate_sdk_base наследует подходящий класс populate_sdk_* (deb, rpm, ipk) в соответствии с IMAGE_PKGTYPE.

Базовый класс убеждается в наличии всех исходных и целевых каталогов, затем заполняет SDK. После этого класс populate_sdk_base создает две файловых системы sysroot — ${SDK_ARCH}-nativesdkсодержит кросс-компилятор и связанные с ним инструменты, а также цель, включающую корневую файловую систему, которая настроена для образа SDK. Эти два образа размещаются в SDK_OUTPUT,как показано ниже.

${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs

В заключение базовый класс заполнения SDK создает сценарий настройки среды инструментов, архив SDK и установщик. Классы populate_sdk_deb, populate_sdk_rpmиpopulate_sdk_ipk поддерживают соответствующие типы SDK. Эти классы наследуются и применяются классом populate_sdk_base.

Дополнительные сведения о создании инструментария кросс-разработки приведены в разделе Cross-Development Toolchain Generation [1]. Преимущества сборки инструментария кросс-разработки с использованием задачи do_populate_sdk описаны в разделе Building an SDK Installer [7].

6.101. `prexport.bbclass`

Класс prexport обеспечивает функциональность поддержки экспорта значений PR. Класс не предназначен для использования на прямую и включается применением bitbake-prserv-tool export.

6.102. `primport.bbclass`

Класс primport обеспечивает функциональность поддержки импорта значений PR. Класс не предназначен для использования на прямую и включается применением bitbake-prserv-tool import.

6.103. `prserv.bbclass`

Класс prserv обеспечивает функциональность для использования сервиса PR при автоматическом управлении переменной PR в каждом задании. Этот класс включен по умолчанию, поскольку он наследуется классом package,однако система сборкиOE не включает эту функциональность, пока не установлена переменная PRSERV_HOST.

6.104. `ptest.bbclass`

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

Этот класс предназначен для наследования индивидуальными заданиями, однако функции класса отключаются, если ptest отсутствует в DISTRO_FEATURES. Тестирование описано в разделе Testing Packages With ptest [2].

6.105. `ptest-gnome.bbclass`

Включает тесты пакетов (ptest) для пакетов GNOME, предназначенных для выполнения с gnome-desktop-testing.

Тестирование описано в разделе Testing Packages With ptest [2].

6.106. `python-dir.bbclass`

Класс python-dir указывает базовую версию и расположение Python, а также расположение пакетов на сайте.

6.107. `python3native.bbclass`

Класс python3native поддерживает применение системой сборки естественной версии Python 3 вместо версии, предоставляемой сборочным хостом.

6.108. `pythonnative.bbclass`

При наследовании заданием класс pythonnative поддерживает использование естественной версии Python, созданной системой сборки, вместо версии, предоставляемой сборочным хостом.

6.109. `qemu.bbclass`

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

6.110. `recipe_sanity.bbclass`

Класс recipe_sanity проверяет выполнение на хосте предварительных условий, которые могут влиять на сборку (например, установку переменных или наличие программ).

6.111. `relocatable.bbclass`

Класс relocatable обеспечивает перемещение (relocation) для исполняемых файлов, установленных в sysroot. Класс применяется классом chrpath и сам использует классы cross и native.

6.112. `remove-libtool.bbclass`

Класс remove-libtool добавляет в задачу do_install функцию удаления всех файлов .la, установленных libtool, и эти файлы не будут включены в sysroot и целевые пакеты. Если файлы .la нужно установить, задание может переопределить удаление, установив REMOVE_LIBTOOL_LA = «0». По умолчанию класс remove-libtool не включен.

6.113. `report-error.bbclass`

Файл report-error поддерживает включение инструмента отчетов об ошибках, который позволяет сохранять сведения об ошибках сборки в единой базе данных. Этот класс собирает отладочную информацию для задания, включая версию задания, систему сборки, целевую систему, ветвь, фиксацию и журнальный файл. Эти данные сохраняются в формате JSON в базе ${LOG_DIR}/error-report.

6.114. `rm_work.bbclass`

Класс rm_work class поддерживает удаление временных рабочих каталогов для экономии дискового пространства. Система сборки OE может занимать значительный объем диска в процессе сборки. Частью занятого пространства являются файлы в каталогах ${TMPDIR}/work каждого задания. Как только система сборки создаст для задания пакеты, эти фалы становятся ненужными. Однако по умолчанию система сборки сохраняет их для проверки и возможной отладки. Если файлы нужно удалить для экономии дискового пространства в процессе сборки, можно включить rm_work by добавлением в файл local.conf каталога сборки строки INHERIT += «rm_work».

Если исходный код размещается вне рабочего каталога задания, включение rm_work может приводить к утрате внесенных в исходный код изменений. Для исключения некоторых заданий из процесса удаления с помощью rm_work можно указать имена этих заданий в файле local.conf с помощью, например, RM_WORK_EXCLUDE += «busybox glibc».

6.115. `rootfs*.bbclass`

Классы rootfs* поддерживают создание корневой файловой системы для образа и включают:

rootfs-postcommands с определением функций пост-обработки в заданиях для образов;
rootfs_deb для создания корневых файловых систем в образах, собираемых с использованием пакетов .deb;
rootfs_rpm для создания корневых файловых систем в образах, собираемых с использованием пакетов .rpm;
rootfs_ipk для создания корневых файловых систем в образах, собираемых с использованием пакетов .ipk;
rootfsdebugfiles для установки дополнительных файлов со сборочного хоста непосредственно в корневую файловую систему.

Корневая файловая система создается с использованием одного из файлов rootfs*.bbclass в соответствии с переменной PACKAGE_CLASSES. Информация о создании образов корневой файловой системы приведена в разделе Image Generation [1].

6.116. `sanity.bbclass`

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

6.117. `scons.bbclass`

Класс scons поддерживает задания для сборки программ, использующих систему сборки SCons. переменная EXTRA_OESCONS позволяет задать дополнительные параметры конфигурации, передаваемые команде scons.

6.118. `sdl.bbclass`

Класс sdl поддерживает задания для сборки программ, использующих библиотеку Simple DirectMedia Layer (SDL).

6.119. `setuptools.bbclass`

Класс setuptools поддерживает расширения Python версии 2.x, используемые системами сборки на основе setuptools. Такие задания должны наследовать класс setuptools.

6.120. `setuptools3.bbclass`

Класс setuptools3 поддерживает расширения Python версии 3.x, используемые системами сборки на основе setuptools. Такие задания должны наследовать класс setuptools3.

6.121. `sign_rpm.bbclass`

Класс sign_rpm поддерживает создание подписанных пакетов RPM.

6.122. `sip.bbclass`

Класс sip поддерживает задания для сборки или упаковки привязок Python на основе SIP.

6.123. `siteconfig.bbclass`

Класс siteconfig поддерживает функциональность настройки конфигурации сайта и применяется классом autotools для ускорения задачи do_configure.

6.124. `siteinfo.bbclass`

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

В качестве примера рассмотрим инструменты Autotools, которым может потребоваться проверка, выполняемая на целевой аппаратной платформе. Поскольку в общем случае это невозможно при кросс-компиляции, используется информация о сайте для предоставления кэшированных результатов тестирования, что эти проверки можно было пропустить с сохранением корректных значений переменных. Результаты тестов хранятся в каталоге meta/site с сортировкой по таким категориям, как архитектура, порядок битов, используемая библиотека libc. Информация о сайте предоставляет список файлов, содержащих данные, относящиеся к конкретной сборке, в переменной CONFIG_SITE, которая автоматически выбирается инструментами Autotools.

Класс также предоставляет такие переменные, как SITEINFO_ENDIANNESS и SITEINFO_BITS, которые могут применяться в метаданных.

6.125. `spdx.bbclass`

Класс spdx объединяет в реальном масштабе времени сканирование лицензий, генерацию стандартного вывода SPDX и проверку лицензий в процессе сборки.

6.126. `sstate.bbclass`

Класс sstate обеспечивает поддержку общего состояния (sstate). По умолчанию класс включен через заданное по умолчанию значение INHERIT_DISTRO. Дополнительные сведения о sstate даны в разделе Shared State Cache [1].

6.127. `staging.bbclass`

Класс staging устанавливает файлы в отдельные рабочие каталоги заданий дляsysroot.

Задача do_populate_sysroot отвечает за обработку файлов, попадающих в sysroot заданий.
Задача do_prepare_recipe_sysroot устанавливает файлы в рабочие каталоги отдельных заданий (WORKDIR).

Код класса staging достаточно сложен и обычно работает в 2 этапа, описанных ниже.

На первом этапе обрабатываются задания, имеющие файлы, которые хотят использовать другие задания, зависящие от данного. Обычно эти зависимости указываются через задачу do_install в ${D}. Задача do_populate_sysroot копирует часть этих файлов в ${SYSROOT_DESTDIR}. Эти файлы определяются переменными SYSROOT_DIRS, SYSROOT_DIRS_NATIVE и SYSROOT_DIRS_BLACKLIST. Кроме того, задание может дополнительно настроить файлы, объявляя функцию обработки в SYSROOT_PREPROCESS_FUNCS.

Из этих файлов создается объект общего состояния, который помещается в каталог tmp/sysroots-components/. Файлы сканируются на предмет жестко заданных путей с местам исходной установки. Если местоположение найдено в текстовом файле, оно заменяется маркерами и создается список файлов, для которых нужны такие замены. Эти корректировки называют FIXME. Список сканируемых файлов определяет SSTATE_SCAN_FILES.
На втором этапе обрабатываются задания, желающие использовать что-либо из других заданий и задающие зависимость в переменной DEPENDS. Задание будет иметь задачу do_prepare_recipe_sysroot,при выполнении которой создаютсяrecipe-sysroot и recipe-sysroot-native в рабочем каталоге (WORKDIR). Система сборки OE создает жесткие ссылки на копии соответствующих файлов из компонент sysrootв рабочий каталог. Если создание жесткой ссылки невозможно, система сборки использует копии. Затем система сборки преобразует FIXME в пути в соответствии со списком, определенным на первом этапе. В заключение выполняются все файлы из ${bindir} в sysroot, имеющие префикс postinst-. Хотя такие сценарии пост-установки не рекомендуются для общего пользования, они позволяют решать некоторые проблемы, такие как создание пользователей или индексы модулей.

Поскольку у заданий могут быть зависимости вне DEPENDS (например, do_unpack[depends] += "tar-native:do_populate_sysroot"), функция создания sysroot extend_recipe_sysroot добавляется в качестве предварительной для задач, чьи зависимости не указаны в DEPENDS,но работают аналогично.

При установке зависимостей в sysroot код просматривает граф зависимостей и обрабатывает их так же, как зависимости из sstate. Это означает, например, что для естественного инструмента будут добавлены естественные зависимости, но не библиотеки для целевой системы. Применяется тот же код обработки зависимостей sstate, поэтому сборки будут идентичными, независимо от использования sstate. Более точное описание приведено для функции setscene_depvalid() в классе sstate.

Система сборки аккуратно поддерживает манифесты устанавливаемых файлов, чтобы можно было установить любую нужную зависимость. Хэш sstate для установленных элементов также сохраняется, чтобы в случае изменения система сборки могла заново установить элемент.

6.128. `syslinux.bbclass`

Класс syslinux обеспечивает функции syslinux для сборки загружаемых образов и включает несколько переменных.

Необязательная переменнаяINITRD указывает список образов файловых систем для объединения и использования в качестве начального RAM-диска (initrd).
Необязательная переменнаяROOTFSуказывает образ файловой системы для включения как корневой.
AUTO_SYSLINUXMENUвключает создание автоматического меня при установке значения«1».
LABELSуказывает цели для автоматической настройки конфигурации.
APPENDуказывает строкуappend переопределяемую для каждой цели (label).
SYSLINUX_OPTSуказывает опции для добавления в файлsyslinux (разделяются символом 😉.
SYSLINUX_SPLASHуказывает фон для загрузочного менюVGA при использовании меню загрузки.
SYSLINUX_DEFAULT_CONSOLEуказывает принятую по умолчанию консоль (console=ttyX) для загрузки ядра.
SYSLINUX_SERIALзадает дополнительный последовательный порт или выключает консоль при пустом имени.
SYSLINUX_SERIAL_TTYзадает дополнительный аргумент загрузки ядра«console=tty…».

6.129. `systemd.bbclass`

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

В этом классе задание или Makefile (что вызывается в задаче do_install) устанавливает файлы модулей в каталог ${D}${systemd_unitdir}/system. Если устанавливаемые модули входят в пакеты, отличные от основного, в задании нужно установить переменную SYSTEMD_PACKAGESдля указания пакетов, в которых будут установлены файлы.

В переменной SYSTEMD_SERVICE нужно указать имя службы, а также следует использовать переопределение имени пакета, к которому применяется значение. Если значение применяется к основному пакету задания, используется ${PN}. Например, для задания connman указывается SYSTEMD_SERVICE_${PN} = «connman.service». Для служб устанавливается автоматический запуск при загрузке, пока не задано SYSTEMD_AUTO_ENABLE = «disable». Дополнительная информация о systemdприведена в разделеSelecting an Initialization Manager [2].

6.130. `systemd-boot.bbclass`

Класс systemd-boot обеспечивает функции для загрузчика systemd-boot при сборке загружаемых образов. Это внутренний класс, не предназначенный для использования напрямую. Этот класс является результатом слияния класса gummiboot из прежних выпусков YP с проектом systemd.

Для использования класса устанавливается EFI_PROVIDER = «systemd-boot», в результате чего создается автономный загрузчик EFI, независимый от systemd. Этот класс использует и поддерживает переменные SYSTEMD_BOOT_CFG, SYSTEMD_BOOT_ENTRIESиSYSTEMD_BOOT_TIMEOUT. См. также документацию Systemd-boot.

6.131. `terminal.bbclass`

Класс terminal обеспечивает поддержку запуска терминальных сессий. Выбор терминала для сессии задает переменная OE_TERMINAL. Класс terminal применяется другими классами при необходимости запуска терминальной сессии. Например, это делает класс patch в предположении PATCHRESOLVE = user, а также классы cml1 и devshell.

6.132. `testimage*.bbclass`

Классы testimage* поддерживают автоматизированное тестирование образов с использованием QEMU и реального оборудования. Классы обслуживают загрузку теста и запуск образа. Для использования классов нужно их настроить в среде разработки. Рекомендуется использовать переменную IMAGE_CLASSES (а не INHERIT) для наследования класса testimage при автоматизированном тестировании образов.

Тестами служат команды, которые запускаются на целевой системе с помощью ssh. Тесты написаны на языке Python и используют модуль unittest.

Класс testimage.bbclass запускает тесты образа при вызове с помощью команды

$ bitbake -c testimage image

Класс testimage-auto выполняет тестирование образа после его создания (требуется TESTIMAGE_AUTO = 1). Дополнительная информация о тестировании представлена в разделе Performing Automated Runtime Testing [2].

6.133. `testsdk.bbclass`

Поддерживает запуск автоматизированных тестов для SDK при вызове

     $ bitbake -c testsdk image

Рекомендуется использовать переменную IMAGE_CLASSES (а не INHERIT) для наследования класса testimage при автоматизированном тестировании SDK.

6.134. `texinfo.bbclass`

Этот класс нужно наследовать заданиям, при сборке которых вызываются утилиты texinfo. Созданы естественные и кросс-задания для использования фиктивных сценариев, обеспечиваемых texinfo-dummy-native, для повышения производительности. Задания для целевой архитектуры используют настоящие утилиты Texinfo (по умолчанию предоставляются хостом). Если нужно использовать задание Texinfo из состава системы сборки, можно удалить texinfo-native из переменной ASSUME_PROVIDED и makeinfo из SANITY_REQUIRED_UTILITIES.

6.135. `tinderclient.bbclass`

Класс tinderclient представляет результаты сборки внешнему экземпляру Tinderbox. Этот класс не поддерживается.

6.136. `toaster.bbclass`

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

6.137. `toolchain-scripts.bbclass`

Класс toolchain-scripts обеспечивает сценарии, используемые при организации среды для установленных SDK.

6.138. `typecheck.bbclass`

Класс typecheck обеспечивает возможность проверки соответствия значений переменных в конфигурации уровня заданным для них типам. Система сборки OE позволяет определять типы с помощью флагов переменных type, например, IMAGE_FEATURES[type] = «list».

6.139. `uboot-config.bbclass`

Класс uboot-config обеспечивает поддержку настройки U-Boot для машины, которая указывается в задании как

     UBOOT_CONFIG ??= <default>
     UBOOT_CONFIG[foo] = "config,images"

Можно также указать машину в форме UBOOT_MACHINE = «config».

6.140. `uninative.bbclass`

Пытается изолировать систему сборки от библиотеки C дистрибутива сборочного хоста, чтобы обеспечить возможность многократного использования элементов общего состояния в разных дистрибутивах хоста. Если этот класс включен, в начале сборки загружается архив с собранной библиотекой C. В эталонном дистрибутиве Poky этот класс включен по умолчанию в файле meta/conf/distro/include/yocto-uninative.inc. Для других дистрибутивов, не основанных на poky также может применяться файл require conf/distro/include/yocto-uninative.inc. Другим вариантом является самостоятельная организация задания uninative-tarball, публикация полученного архива (например, по HTTP) и соответствующая установка переменных UNINATIVE_URL и UNINATIVE_CHECKSUM. Примером может служить файл meta/conf/distro/include/yocto-uninative.inc.

Класс uninative также безоговорочно применяется в eSDK. При сборке расширяемого SDK собирается uninative-tarball и полученный архив включается в SDK.

6.141. `update-alternatives.bbclass`

Класс update-alternatives помогает выбору вариантов при наличии нескольких источников, представляющих одну команду. Такие ситуации возникают, когда несколько команд, обеспечивающих одну или близкие функции, устанавливаются с одним именем. Например, команда ar доступна в busybox, binutils и elfutils. Класс update-alternatives обрабатывает переименование двоичных файлов, позволяя установить множество пакетов без конфликта. Команда ar будет работать независимо от того, какие пакеты установлены или впоследствии удалены. Класс переименовывает двоичные файлы в каждом пакете и создает символьную ссылку на пакет с высшим приоритетом при установке или удалении пакетов.

Для использования класса нужно определить несколько переменных:

ALTERNATIVE;
ALTERNATIVE_LINK_NAME;
ALTERNATIVE_TARGET;
ALTERNATIVE_PRIORITY.

Эти переменные указывают варианты команд, нужные пакету, обеспечивают пути для ссылок, используемые по умолчанию ссылки для целей и т. п. Информация по использованию переменных приведена в комментариях к файлу update-alternatives.bbclass.

Можно использовать команду update-alternatives непосредственно в заданиях, однако с классом в большинстве случаев работать проще.

6.142. `update-rc.d.bbclass`

Класс update-rc.d использует update-rc.d для безопасной установки сценариев инициализации от имени приложений. Система сборки OE заботится о таких деталях, как гарантии остановки сценария перед удалением пакета и запуска при установке. Управляют классом переменные INITSCRIPT_PACKAGES, INITSCRIPT_NAME и INITSCRIPT_PARAMS.

6.143. `useradd*.bbclass`

Классы useradd* поддерживают добавление пользователей или групп для пакетов на целевой платформе. Например, при наличии пакетов с системными службами, которые следует запускать от имени пользователя или группы, можно воспользоваться этими классами для возможности включения этих пользователей или групп. Задание meta-skeleton/recipes-skeleton/useradd/useradd-example.bb в дереве исходных кодов содержит простой пример, показывающий добавление трех пользователей и групп для двух пакетов.

Класс useradd_base обеспечивает базовую функциональность для работы с пользователями и группами. Классы useradd* поддерживают переменные USERADD_PACKAGES, USERADD_PARAM, GROUPADD_PARAMи GROUPMEMS_PARAM. Класс useradd-staticids поддерживает добавление пользователей и групп со статическими значениями идентификаторов uidиgid. По умолчанию система сборки OE назначает значения uid и gid при добавлении пакетами пользователей и групп динамически во время установки пакета. Это хорошо работает для программ, которые не заботятся об окончательных значениях идентификаторов пользователей и групп. Однако при возникновении проблем с использованием недетерминированных значений uid и gidможно переопределить поведение, задав статические идентификаторы. В этом случае системасборкиOE смотрит нужные значения в файлах files/passwd и files/group по путиBBPATH. Для использования статических значений uid и gid нужно задать несколько переменных (USERADDEXTENSION, USERADD_UID_TABLES, USERADD_GID_TABLES, USERADD_ERROR_DYNAMIC).

Класс useradd-staticids не используется напрямую, а включается или отключается через переменную USERADDEXTENSION. Если включить или отключить класс в настроенной системе, в TMPDIR могут оказаться некорректные значения uid и gid,однако удалениеTMPDIR позволяет решить эту проблему.

6.144. `utility-tasks.bbclass`

Класс utility-tasks обеспечивает поддержку вспомогательных задач, применяемых для всех заданий, таких как do_clean и do_listtasks. Класс включен по умолчанию, поскольку он наследуется классом base.

6.145. `utils.bbclass`

Класс utils обеспечивает некоторые полезные функции Python, которые обычно применяются в inline-выражениях Python (например, ${@...}). Класс включен по умолчанию, поскольку он наследуется классом base.

6.146. `vala.bbclass`

Класс vala поддерживает задания, которым нужно собирать программы, написанные с использованием языка Vala.

6.147. `waf.bbclass`

Класс waf поддерживает задания, собирающие программы с использованием системы сборки Waf. Переменная EXTRA_OECONF или PACKAGECONFIG_CONFARGS позволяет задать дополнительные параметры конфигурации, передаваемые Waf.

Глава 7. Задачи

Задачи являются блоками выполнения BitBake. Задания (файлы .bb) применяют задачи для настройки, компиляции и упаковки программ. В этой главе приведен справочник по задачам, определенным в системе сборки OE.

7.1. Обычные задачи сборки заданий

В последующих параграфах рассмотрены обычные задачи, связанные со сборкой заданий. Дополнительные сведения о задачах и зависимостях приведены в разделах Tasks и Dependencies[4].

7.1.1. `do_build`

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

7.1.2. `do_compile`

Компиляция исходного кода. Задача выполняется из каталога, заданного переменной ${B}. По умолчанию эта задача вызывает функцию oe_runmake,если найден файл сборки (Makefile, makefileилиGNUmakefile). В противном случае do_compile не делает ничего.

7.1.3. `do_compile_ptest_base`

Компилирует набор используемых при работе (runtime) тестов, который включен в собираемое задание.

7.1.4. `do_configure`

Настраивает исходные коды выбирая опции конфигурации и сборки для собираемой программы. Задача выполняется в текущем рабочем каталоге, заданном переменной ${B}. По умолчанию эта задача вызывает функцию oe_runmake,если найден файл сборки (Makefile, makefileилиGNUmakefile) и не установлено CLEANBROKEN = «1». В противном случае do_configure не делает ничего.

7.1.5. `do_configure_ptest_base`

Настраивает набор runtime-тестов, включаемых в собираемые программы.

7.1.6. `do_deploy`

Записывает выходные файлы для развертывания в ${DEPLOY_DIR_IMAGE}. Задача выполняется из текущего рабочего каталога, указанного ${B}. Заданиям, применяющим эту задачу, нужно наследовать класс deploy и записывать вывод в каталог ${DEPLOYDIR}(не следует путать его с${DEPLOY_DIR}). Класс deploy устанавливает do_deploy как задачу с общим состоянием (sstate), которую можно ускорить с помощью механизма sstate, обеспечивающего копирование вывода из ${DEPLOYDIR} в ${DEPLOY_DIR_IMAGE}. Не записывайте вывод напрямую в ${DEPLOY_DIR_IMAGE}, поскольку это нарушит работу sstate.

Задача do_deploy не добавляется по умолчанию и должна указываться вручную. Если нужно запустить задачу после do_compile, можно выполнить

     addtask deploy after do_compile

Добавление do_deploy после других задач выполняется так же. Не нужно добавлять before do_build в команду addtask (хотя это безвредно), поскольку класс base содержит

     do_build[recrdeptask] += "do_deploy"

Дополнительная информация о развертывании приведена в разделе Dependencies [4].

При повторном выполнении задачи do_deploy предыдущий вывод удаляется (очищается).

7.1.7. `do_fetch`

Извлекает исходный код, используя переменную SRC_URI и префикс аргумента для определения нужного сборщика.

7.1.8. `do_image`

Запускает процесс создания образа после того, как система сборки OE выполнит задачу do_rootfs,в которой указываются выбранные для установки приложения, создается корневая файловая система и выполняется пост-обработка. Задача do_image выполняет предварительную обработку образа с помощью IMAGE_PREPROCESS_COMMAND и динамически генерирует при необходимости задачи do_image_*. Дополнительные сведения о создании образов приведены в разделе Image Generation [1].

7.1.9. `do_image_complete`

Завершает процесс генерации образа. Эта задача выполняется после того, как система сборки OE запустит задачу do_image,в которой выполняется предварительная обработка и создается образ с помощью динамически генерируемых задачdo_image_*.

Задача do_image_complete выполня пост-обработку образа с помощью IMAGE_POSTPROCESS_COMMAND. Создание образов описано в разделе Image Generation [1].

7.1.10. `do_install`

Копирование файлов, которые должны быть включены в пакет, в область ${D}. Задача выполняется из каталога, заданного переменной${B}, который служит каталогом компиляции. Задача do_install, как и другие задачи, напрямую или косвенно зависящие от установленных файлов (например do_package, do_package_write_*, do_rootfs), запускаются в fakeroot [1].

При установке файлов нужно соблюдать осторожность в выборе идентификаторов владельца и группы, чтобы для них не были указаны неопределенные значения. Некоторые методы копирования файлов, особенно команда cp с рекурсией, могут сохранять UID и/или GID исходного файла, что обычно нежелательно. Проверка host-user-contaminated позволяет контролировать владельца и группу для файлов.

Ниже перечислены некоторые методы установки файлов.

Утилита install (предпочтительный вариант).
Команда cp с опцией —no-preserve=ownership.
Команда tar с опцией —no-same-owner (см. файл bin_package.bbclass в каталоге meta/classes дерева кодов).

7.1.11. `do_install_ptest_base`

Копирует файлы набора тестов runtime из области компиляции в область хранения.

7.1.12. `do_package`

Анализирует содержимое области ${D} и разделяет его на части по доступным пакетам и файлам. Задача использует переменные PACKAGES и FILES.

Задача do_package вместе с do_packagedata сохраняет некоторые важные метаданные пакетов (см. описание переменной PKGDESTWORK и раздел Automatically Added Runtime Dependencies [1]).

7.1.13. `do_package_qa`

Запускает проверки QA для файлов пакета (см. параграф 6.56. insane.bbclass).

7.1.14. `do_package_write_deb`

Создает пакеты Debian (файлы *.deb) и помещает их в каталог ${DEPLOY_DIR_DEB} в области источника пакетов. Дополнительные сведения об упаковке приведены в разделе Package Feeds [1].

7.1.15. `do_package_write_ipk`

Создает пакеты IPK ( файлы *.ipk) и помещает их в каталог ${DEPLOY_DIR_IPK} в области источника пакетов. Дополнительные сведения об упаковке приведены в разделе Package Feeds [1].

7.1.16. `do_package_write_rpm`

Создает пакеты RPM ( файлы *.rpm) и помещает их в каталог ${DEPLOY_DIR_RPM} в области источника пакетов. Дополнительные сведения об упаковке приведены в разделе Package Feeds [1].

7.1.17. `do_package_write_tar`

Создает архивы (tarball) и помещает их в каталог ${DEPLOY_DIR_TAR} (см. раздел Package Feeds [1]).

7.1.18. `do_packagedata`

Сохраняет метаданные пакеты, созданные задачей do_package в каталоге PKGDATA_DIR для глобального доступа.

7.1.19. `do_patch`

Находит patch-файлы и применяет их к исходному коду. После извлечения и распаковки исходных файлов система сборки использует операторы SRC_URI из задания для поиска и применения исправлений к исходному коду. Система сборки использует переменную FILESPATH для определения принятого по умолчанию набора каталогов поиска patch-файлов. Файлы исправлений по умолчанию используют расширение *.patch или *.diff и хранятся в подкаталоге каталога с файлом задания. Например, задание bluez5 уровня OE-Core (poky/meta) использует каталог poky/meta/recipes-connectivity/bluez5 и включает два patch-файла. В задании bluez5 операторы SRC_URI указывают на исходные файлы и исправления, нужные для сборки пакета.

В случае задания bluez5_5.48.bb операторы применяются SRC_URI из включаемого файла bluez5.inc.

Как отмечено выше, система сборки считает файлы с расширениями .patch и .diff файлами исправлений. Однако можно использовать параметр apply=yes с оператором SRC_URI для указания в качестве исправлений любых файлов.

SRC_URI = " \
          git://path_to_repo/some_package \ file://file;apply=yes \ "

И наоборот, если у вас есть целый каталог patch-файлов и нужно исключить применение части их задачей do_patch,следует использовать параметрapply=no с оператором SRC_URI.

SRC_URI = " \
          git://path_to_repo/some_package \ file://path_to_lots_of_patch_files \ file://path_to_lots_of_patch_files/patch_file5;apply=no \ "

Если все файлы в каталоге имеют расширение .patch или .diff, будут применены все исправления, кроме patch_file5.

Дополнительная информация о применении patch-файлов дана в разделах Patching [1] и Patching Code [2].

7.1.20. `do_populate_lic`

Записывает лицензионную информацию для задания, которая затем собирается при создании образа.

7.1.21. `do_populate_sdk`

Создает структуру файлов и каталогов для устанавливаемого SDK (см. раздел SDK Generation [1]).

7.1.22. `do_populate_sysroot`

Помещает (копирует) часть файлов, установленных задачей do_install в соответствующий каталог sysroot. Информация о доступе к этим файлам из других заданий приведена в описаниях переменных STAGING_DIR*. Каталоги, которые обычно не нужны другим заданиям (например, /etc), по умолчанию не копируются. Копируемые по умолчанию каталоги приведены в описаниях переменных SYSROOT_DIRS*. Значения этих переменных можно изменить в задании, если нужно добавить или исключить каталоги, доступные другим заданиям в процессе сборки.

Задача do_populate_sysroot относится к задачам с общим состоянием (sstate), что позволяет ускорить ее с помощью sstate. При повторном выполнении задачи предшествующий вывод удаляется (очистка).

7.1.23. `do_prepare_recipe_sysroot`

Устанавливает файлы в sysroot отдельных заданий (т. е. recipe-sysroot и recipe-sysroot-native в каталоге ${WORKDIR} на основе зависимостей из DEPENDS). Дополнительная информация приведена в параграфе 6.127. staging.bbclass.

7.1.24. `do_rm_work`

Удаляет рабочие файлы после завершения их использования системой сборки OE (см. параграф 6.114. rm_work.bbclass).

7.1.25. `do_unpack`

Распаковывает исходный код в рабочий каталог, указанный ${WORKDIR}. Переменная S тоже играет роль в выборе окончательного места размещения распакованных файлов. Дополнительная информация о распаковке файлов исходного кода приведена в разделе Source Fetching [1] а также описаниях переменных WORKDIR и S.

7.2. Вызываемые вручную задачи

Описанные в этом разделе задачи обычно запускаются вручную, например, с помощью bitbake -c.

7.2.1. `do_checkpkg`

Обеспечивает информацию о задании, включая «восходящую» версию и статус. Для проверки версии и статуса задания служат приведенные ниже команды devtool (Глава 8. Краткий справочник по работе с devtool).

     $ devtool latest-version
     $ devtool check-upgrade-status

Информация о проверке статуса обновления задания приведена в параграфе 8.9. Проверка статуса обновления задания. Для сборки задачи checkpkg используется опция -c с именем задачи, как показано ниже.

     $ bitbake core-image-minimal -c checkpkg

По умолчанию результат сохраняется в $LOG_DIR (например, $BUILD_DIR/tmp/log).

7.2.2. `do_checkuri`

Проверяет пригодность значения SRC_URI.

7.2.3. `do_clean`

Удаляет все выходные файлы для цели от задачи do_unpack вперед (do_unpack, do_configure, do_compile, do_install, do_package). Задача запускается командой bitbake -c clean recipe.Запуск задачи не удаляет кэш-файлы sstate, поэтому при отсутствии изменений и пересборке задания после очистки, выходные файлы будут просто восстановлены из кэша sstate. Если нужно удалить кэш для задания, должна применяться задача do_cleansstate (bitbake -c cleansstate recipe).

7.2.4. `do_cleanall`

Удаляет все выходные файлы, кэш общего состояния (sstate) и загруженные файлы для цели (содержимое DL_DIR). Задача do_cleanall идентична do_cleansstate за исключением того, что удаляет загруженные исходные файлы. Задача запускается командой bitbake -c cleanall recipe.Обычно задачаcleanall не применяется, если не нужно начать сборку заново с задачи do_fetch.

7.2.5. `do_cleansstate`

Удаляет все выходные файлы и кэш общего состояния (sstate) файлы для цели. Задача do_cleansstate идентична do_clean,но дополнительно удаляет кэш общего состояния(sstate). Задача запускается командой bitbake -c cleansstate recipe.При запускеdo_cleansstate система сборки OE больше не применяет sstate, поэтому гарантируется сборка задания «с нуля».

Задача do_cleansstate не может удалять файлы sstate с удаленного зеркала sstate. Если нужно собрать цель с нуля при использовании удаленных зеркал, нужно задать опцию -f, как показано ниже.

$ bitbake -f -c do_cleansstate target

7.2.6. `do_devpyshell`

Запускает оболочку, в которой интерактивный интерпретатор Python позволяет взаимодействовать со средой сборки BitBake. Из этой оболочки можно напрямую проверять и устанавливать биты из хранилища данных, а также вызывать функции как в среде BitBake. Описание devpyshell приведено в разделе Using a Development Python Shell [2].

7.2.7. `do_devshell`

Запускает оболочку со средой, настроенной на разработку и/или отладку. Работа с оболочкой devshell описана в разделе Using a Development Shell [2].

7.2.8. `do_listtasks`

Перечисляет определенные для цели задачи.

7.2.9. `do_package_index`

Создает или обновляет индекс в области хранилищ пакетов. Эта задача не вызывается командой bitbake -c как другие задачи этого раздела. Поскольку задача предназначена для задания package-index, она вызывается командой bitbake package-index.

7.3. Задачи, связанные с образами

Перечисленные ниже задачи относятся к заданиям для образов.

7.3.1. `do_bootimg`

Создает загружаемый live-образ. Типы образов рассмотрены в описании переменной IMAGE_FSTYPES.

7.3.2. `do_bundle_initramfs`

Объединяет образ initramfs и ядро в один образ (см. CONFIG_INITRAMFS_SOURCE).

7.3.3. `do_rootfs`

Создает корневую файловую систему (см. раздел Image Generation [1]).

7.3.4. `do_testimage`

Загружает образ и выполняет тесты на нем (см. раздел Performing Automated Runtime Testing [2]).

7.3.5. `do_testimage_auto`

Загружает образ и выполняет тесты на нем сразу после сборки. Задача включается установкой TESTIMAGE_AUTO = 1.

Дополнительную информацию можно найти в разделе Performing Automated Runtime Testing [2].

7.4. Задачи, связанные с ядром

Описанные ниже задачи относятся к заданиям для ядра. Некоторые задачи (например, do_menuconfig) применимы также к заданиям, использующим настройку в стиле ядра Linux (например BusyBox).

7.4.1. `do_compile_kernelmodules`

Запускает этап сборки модулей ядра (если нужно), включающий 1) сборку ядра (vmlinux) и 2) модулей (make modules).

7.4.2. `do_diffconfig`

При вызове пользователем эта задача создает файл, содержащий различия между исходной конфигурацией, созданной задачей do_kernel_configme и пользовательской конфигурацией (например, результат do_kernel_menuconfig). Этот файл может служить для создания фрагмента конфигурации, содержащего лишь различия. Задачу можно вызвать командой вида bitbake linux-yocto -c diffconfig.

Дополнительную информацию можно найти в разделе Creating Configuration Fragments [3].

7.4.3. `do_kernel_checkout`

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

7.4.4. `do_kernel_configcheck`

Служит для проверки конфигурации, созданной задачей do_kernel_menuconfig и выводит предупреждения в случае отсутствия запрошенной конфигурации в финальном файле .config или переопределения правил конфигурации во фрагменте аппаратной конфигурации. Задачу можно запустить явно для просмотра вывода с помощью команды bitbake linux-yocto -c kernel_configcheck -f. Дополнительные сведения можно найти в разделе Validating Configuration [3].

7.4.5. `do_kernel_configme`

После наложения правок на ядро с помощью задачи do_patch задача do_kernel_configme собирает и объединяет все фрагменты конфигурации ядра, которые затем могут быть переданы этапу настройки конфигурации. Здесь также применяются опции из заданных пользователем файлов defconfig и режимы настройки --allnoconfig.

7.4.6. `do_kernel_menuconfig`

Вызывается пользователем для работы с файлом .config,используемым для сборки задания linux-yocto и запускает инструмент настройки конфигурации ядра Linux, который позволяет настроить параметры ядра. Эту задачу можно запустить командой bitbake linux-yocto -c menuconfig. Информация о настройке конфигурации ядра приведена в разделе Using menuconfig[3].

7.4.7. `do_kernel_metadata`

Собирает все свойства, нужные для сборки данного ядра, независимо от их источника (SRC_URI или репозиторий Git). После сбора задача преобразует свойства в набор фрагментов конфигурации и patch-файлов, применяемых последующими задачами, такими как do_patch и do_kernel_configme.

7.4.8. `do_menuconfig`

Запускает команду make menuconfig для ядра (см. раздел Using menuconfig [3]).

7.4.9. `do_savedefconfig`

При вызове пользователем создает файл defconfig, который может использоваться вместо принятого по умолчанию. Сохраненный файл defconfig содержит различия между заданным по умолчанию файлом defconfig и внесенные пользователем изменения (с использованием других методов, таких как задача do_kernel_menuconfig). Задачу можно вызвать командой bitbake linux-yocto -c savedefconfig.

7.4.10. `do_shared_workdir`

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

7.4.11. `do_sizecheck`

После сборки ядра эта задача проверяет размер ядра с вырезанными символами, сравнивая его с переменной KERNEL_IMAGE_MAXSIZE. Если переменная задана и размер ядра превышает ее значение, выдается предупреждение.

7.4.12. `do_strip`

При установленной переменной KERNEL_IMAGE_STRIP_EXTRA_SECTIONS эта задача вырезает заданные переменной разделы из файла vmlinux. Обычно это применяется для исключения таких разделов как .comment для снижения размера ядра.

7.4.13. `do_validate_branches`

После распаковки ядра и перед наложением правок (patch) эта задача проверяет наличие ветвей машины и метаданных, указанных переменной SRCREV. Если ветви не найдены, а переменная AUTOREV не используется, задача do_validate_branches вызывает ошибку сборки.

7.5. Прочие задачи

7.5.1. `do_spdx`

Этап сборки, принимающий исходный код и сканирующий его на удаленном сервере FOSSOLOGY для создания документа SPDX. Задача применима только к классу spdx.

Глава 8. Краткий справочник по работе с `devtool`

Консольный инструмент devtool обеспечивает множество функций для сборки, тестирования и подготовки пакетов. Эта команда доступная вместе с bitbake и является важнейшей частью расширяемых SDK. Здесь приведено краткое описание devtool, а более полные сведения содержатся в разделе Using the Extensible SDK [7].

8.1. Получение справки

Команды devtool организованы подобно Git и включают множество субкоманд для разных функций, которые можно увидеть по команде devtool —help.

     $ devtool -h
     NOTE: Starting bitbake server...
     usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
                    [--color COLOR] [-h]
                    <subcommand> ...

     OpenEmbedded development tool

     options:
       --basepath BASEPATH   Base directory of SDK / build directory
       --bbpath BBPATH       Explicitly specify the BBPATH, rather than getting it
                             from the metadata
       -d, --debug           Enable debug output
       -q, --quiet           Print only errors
       --color COLOR         Colorize output (where COLOR is auto, always, never)
       -h, --help            show this help message and exit

     subcommands:
       Beginning work on a recipe:
         add                   Add a new recipe
         modify                Modify the source for an existing recipe
         upgrade               Upgrade an existing recipe
       Getting information:
         status                Show workspace status
         search                Search available recipes
         latest-version        Report the latest version of an existing recipe
         check-upgrade-status  Report upgradability for multiple (or all) recipes
       Working on a recipe in the workspace:
         build                 Build a recipe
         rename                Rename a recipe file in the workspace
         edit-recipe           Edit a recipe file
         find-recipe           Find a recipe file
         configure-help        Get help on configure script options
         update-recipe         Apply changes from external source tree to recipe
         reset                 Remove a recipe from your workspace
         finish                Finish working on a recipe in your workspace
       Testing changes on target:
         deploy-target         Deploy recipe output files to live target machine
         undeploy-target       Undeploy recipe output files in live target machine
         build-image           Build image including workspace recipe packages
       Advanced:
         create-workspace      Set up workspace in an alternative location
         export                Export workspace into a tar archive
         import                Import exported tar archive into workspace
         extract               Extract the source for an existing recipe
         sync                  Synchronize the source tree for an existing recipe
     Use devtool <subcommand> --help to get help on a specific command

Как указано на справочной странице можно получить дополнительные сведения о конкретных командах, указав имя команды и опцию —help.

     $ devtool add --help
     NOTE: Starting bitbake server...
     usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
                        [--fetch-dev] [--version VERSION] [--no-git]
                        [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH]
                        [--binary] [--also-native] [--src-subdir SUBDIR]
                        [--mirrors] [--provides PROVIDES]
                        [recipename] [srctree] [fetchuri]

     Adds a new recipe to the workspace to build a specified source tree. Can
     optionally fetch a remote URI and unpack it to create the source tree.

     arguments:
       recipename            Name for new recipe to add (just name - no version,
                             path or extension). If not specified, will attempt to
                             auto-detect it.
       srctree               Path to external source tree. If not specified, a
                             subdirectory of
                             /home/scottrif/poky/build/workspace/sources will be
                             used.
       fetchuri              Fetch the specified URI and extract it to create the
                             source tree

     options:
       -h, --help            show this help message and exit
       --same-dir, -s        Build in same directory as source
       --no-same-dir         Force build in a separate build directory
       --fetch URI, -f URI   Fetch the specified URI and extract it to create the
                             source tree (deprecated - pass as positional argument
                             instead)
       --fetch-dev           For npm, also fetch devDependencies
       --version VERSION, -V VERSION
                             Version to use within recipe (PV)
       --no-git, -g          If fetching source, do not set up source tree as a git
                             repository
       --srcrev SRCREV, -S SRCREV
                             Source revision to fetch if fetching from an SCM such
                             as git (default latest)
       --autorev, -a         When fetching from a git repository, set SRCREV in the
                             recipe to a floating revision instead of fixed
       --srcbranch SRCBRANCH, -B SRCBRANCH
                             Branch in source repository if fetching from an SCM
                             such as git (default master)
       --binary, -b          Treat the source tree as something that should be
                             installed verbatim (no compilation, same directory
                             structure). Useful with binary packages e.g. RPMs.
       --also-native         Also add native variant (i.e. support building recipe
                             for the build host as well as the target machine)
       --src-subdir SUBDIR   Specify subdirectory within source tree to use
       --mirrors             Enable PREMIRRORS and MIRRORS for source tree fetching
                             (disable by default).
       --provides PROVIDES, -p PROVIDES
                             Specify an alias for the item provided by the recipe.
                             E.g. virtual/libgl

8.2. Структура уровня `workspace`

Команда devtool использует уровень Workspace, в котором выполняется сборка. Этот уровень не связан с какой-либо конкретной командой devtool, а служит рабочей областью для инструмента. Структура workspace показана на рисунке.

attic

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

README

Информация об уровне workspace и управлении им.

.devtool_md5

Файл контрольной суммы, используемый devtool.

appends

Каталог с файлами *.bbappend, указывающими внешний источник.

conf

Конфигурационный каталог с файлом layer.conf.

recipes

Каталог с заданиями, каждое из которых размещается с своем каталоге, имя которого соответствует имени задания. Программа devtool помещает в эти каталоги файлы .bb для заданий.

sources

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

8.3. Добавление задания на уровень workspace

Команда devtool add добавляет задание на уровень workspace. Задание не нужно создавать заранее, это сделает devtool. Файлы исходных кодов для задания должны размещаться во внешней области.

Ниже приведен пример, добавляющий задание jackson на уровень workspace и исходными кодами из каталога /home/user/sources/jackson.

$ devtool add jackson /home/user/sources/jackson

Если в момент добавления задания уровня workspace еще не было, команда создаст его и заполнит в соответствии с параграфом 8.2. Структура уровня workspace. Если уровень уже создан, команда devtool add добавит файлы задания и дополнения, а также файлы исходного кода в существующую структуру. Создается файл .bbappend для указания внешнего дерева источников.

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

По умолчанию devtool add использует последний выпуск (т. е. master) при извлечении файлов из удаленного URI. В некоторых случаях можно задать выпуск по ветви, тегу или хэш-значению фиксации опциями команды devtool add.

Для задания ветви служит опция --srcbranch (выбирает ветвь warrior)
```
$ devtool add --srcbranch warrior jackson /home/user/sources/jackson
```
Для задания тега или хэш-значения служит опция --srcrev.
```
$ devtool add --srcrev yocto-2.7.1 jackson /home/user/sources/jackson $ devtool add --srcrev some_commit_hash /home/user/sources/jackson
```
В этих примерах выбирается тег yocto-2.7.1 и фиксация с хэшем some_commit_hash.

Если нужно использовать наиболее свежую версию при каждой сборке, следует указать опцию --autorev или -a.

8.4. Извлечение исходного кода для имеющегося задания

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

8.5. Синхронизация дерева исходного кода

Команда devtool sync позволяет синхронизировать исходный код для имеющегося задания. В команде нужно указать имя задания (без версии, пути и расширения) вместе с каталогом, куда следует поместить извлеченные файлы. Опции команды позволяют указать ветвь, в которую будет извлекаться код, и управлять сохранением временного каталога.

8.6. Изменение задания

Команда devtool modify служит для изменения источников имеющегося задания. Она похожа на команду add, но не создает нового задания на уровне workspace, поскольку задание уже присутствует в другом уровне. Команда извлекает файлы исходного кода, организуя их в локальный репозиторий Git, если источник еще не был получен из Git, выбирает ветвь для разработки и применяет все правки, зафиксированные (commit) в задании. При вводе команды devtool modify recipe программа devtool будет использовать оператор SRC_URI в имеющемся задании для указания восходящего источника и извлечет исходные файлы в заданное по умолчанию место, используя по умолчанию ветвь devtool.

8.7. Редактирование задания

Команда devtool edit-recipe запускает редактор, указанный в переменной EDITOR внутри файла задания. В команде нужно указывать корневое имя задания (без версии и расширения), а файл задания должен размещаться в структуре workspace. Однако эти требования можно переопределить с помощью опции -a или —any-recipe.

8.8. Обновление задания

Команда devtool update-recipe служит для обновления задания правками (patch), отражающими изменения в исходных файлах. Например, при намерении работать с тем или иным кодом можно сначала использовать команду devtool modify для извлечения кода и организации рабочего пространства. Затем можно изменить, скомпилировать и протестировать код. Когда результат будет достигнут и изменения зафиксированы (commit) в репозитории Git, можно воспользоваться командой devtool update-recipe для создания patch-файлов и обновления задания.

$ devtool update-recipe recipe

Команда devtool update-recipe будет игнорировать незафиксированные изменения.

Зачастую программные настройки будут меняться в пользовательском уровне а не в исходном задании. В таких случаях можно использовать опцию -a или --append в команде devtool update-recipe,позволяющую указать уровень.

$ devtool update-recipe recipe -a base-layer-directory

При этом создается файл дополнения *.bbappend в нужном каталоге указанного уровня, который может (не обязательно) быть включен в файл bblayers.conf. Если файл дополнения уже имеется, команда обновит его.

8.9. Проверка статуса обновления задания

Восходящие задания время от времени меняются, поэтому может возникнуть потребность в их обновлении. Для проверки статуса задания служит команда devtool check-upgrade-status,которая выводит таблицу текущих версий заданий, последних версий этих заданий, адреса электронной почты сопровождающих и другую информацию, такую как хэш-значения фиксаций и возможные причины обновления. Для уровняoe-core адреса сопровождающих берутся из файла maintainers.inc. Если задание использует сборщик Git fetcher, а не архив, хэш фиксации указывается для тега последней версии.

Как для всех команд devtool можно получить справку

     $ devtool check-upgrade-status -h
     NOTE: Starting bitbake server...
     usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]]

     Prints a table of recipes together with versions currently provided by
     recipes, and latest upstream versions, when there is a later version available

     arguments:
       recipe      Name of the recipe to report (omit to report upgrade info for
                   all recipes)

     options:
      -h, --help  show this help message and exit
       --all, -a   Show all recipes, not just recipes needing upgrade

Если в команде не указано конкретное задание, проверяться будут все заданий для всех уровней в конфигурации. Ниже приведена часть выходной таблицы для всех заданий. Отметим, что в списке указана причина не обновлять задание base-passwd,связанная с тем, что для этого требуется обновить такжеcdebconf,что достаточно сложно. Когда причина отказа от обновления указана, она обычно записывается в файл задания (RECIPE_NO_UPDATE_REASON). Пример можно найти в файлеbase-passwd.bb.

     $ devtool check-upgrade-status
         ...
         NOTE: acpid                     2.0.30          2.0.31
     Ross Burton <ross.burton@intel.com>
         NOTE: u-boot-fw-utils           2018.11         2019.01
     Marek Vasut <marek.vasut@gmail.com>
     d3689267f92c5956e09cc7d1baa4700141662bff
         NOTE: u-boot-tools              2018.11         2019.01
     Marek Vasut <marek.vasut@gmail.com>
     d3689267f92c5956e09cc7d1baa4700141662bff
          ...
         NOTE: base-passwd               3.5.29          3.5.45
     Anuj Mittal <anuj.mittal@intel.com>  cannot be updated due to: Version
     3.5.38 requires cdebconf for update-passwd utility
         NOTE: busybox                   1.29.2          1.30.0
     Andrej Valek <andrej.valek@siemens.com>
         NOTE: dbus-test                 1.12.10         1.12.12
     Chen Qi <Qi.Chen@windriver.com>

8.10. Обновление задания

По мере развития программ задания обновляются с новыми версиями. Разработчику следует поддерживать актуальность своих локальных заданий, для чего имеется несколько методов, описанных в разделе Upgrading Recipes [2]. Здесь описано обновление с помощью команды devtool upgrade. Перед обновлением задания следует проверить его статус, как описано в параграфе 8.9. Проверка статуса обновления задания.

Команда devtool upgrade обновляет имеющееся задание до последней версии восходящего источника. Файл обновленного задания и связанные с ним файлы помещаются в workspace и при необходимости распаковываются в указанное место дерева источников. В процессе обновления связанные с заданием patch-файлы также обновляются или добавляются.

При использовании команды devtool upgrade нужно указывать базовое имя задания (без версии, пути и расширения), а также каталог, в который нужно извлечь исходный код. Опции команды позволяют управлять номером версии для обновления (PV), выпуском (SRCREV), применением patch-файлов и т. п.

Дополнительную информацию о работе с devtoolможно найти в разделеUse devtool upgrade to Create a Version of the Recipe that Supports a Newer Version of the Software [7], а примеры использования devtool upgrade — в Using devtool upgrade [2].

8.11. Сброс задания

Команда devtool reset удаляет задание и его конфигурацию (например, файл .bbappend) с уровня workspace. Следует понимать, что команда не переносит файлов задания, поэтому нужно поместить завершенное задание и файл дополнения в нужное место за пределами workspace перед использованием команды devtool reset. Если команда devtool reset обнаруживает, что файл задания или дополнения был изменен, эти измененные файлы сохраняются в каталоге attic на уровне workspace. Ниже приведен пример сброса каталога workspace, содержащего задание mtr.

$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
  longer need it then please delete it manually

8.12. Сборка задания

Команда devtool build служит для сборки заданий и эквивалентна команде bitbake -c populate_sysroot. При использовании команды нужно указывать базовое имя задания (без версии, пути и расширения). Опция -s или —disable-parallel-make позволяет отключить при сборке параллельные операции.

8.13. Сборка образа

Команда devtool build-image служит для сборки образа со включением в него пакетов из workspace. Команда удобна для создания образов в процессе тестирования приложений. Для окончательной установки пакета в образ следует отредактировать задание для образа. Команда требует указать образ, куда включаются пакеты и имеет вид

$ devtool build-image image

8.14. Развертывание программ на целевой машине

Команда devtool deploy-target служит для развертывания вывода сборки «вживую» на целевой машине.

$ devtool deploy-target recipe target

Цель указывается адресом или именем и должна поддерживать сервер SSH (user@hostname[:destdir]).

Команда размещает все файлы, установленные задачей do_install. На целевой платформе не требуется менеджер пакетов, а при наличии он обходится. Команда deploy-target предназначена лишь для разработки и ее не следует применять для создания окончательного образа.

Поведение развернутых приложений в некоторых случаях может оказаться неожиданным, если развертывается новое приложение, задание для сборки которого учитывает все рабочие зависимости, на целевой платформе нет пакетов, от которых приложение зависит. Некорректное поведение объясняется тем, что команда devtool deploy-target не развертывает пакеты (например, библиотеки), от которых зависит новое приложение. Поэтому при вызове новым приложением отсутствующей функции результаты могут быть неожиданными. Для предотвращения подобных проблем следует заранее установить все нужные пакеты на целевой платформе.

8.15. Удаление программ с целевой машины

Команда devtool undeploy-target позволяет удалить развернутый на целевой машине вывод сборки, перенесенный туда ранее командой devtool deploy-target. Цель указывается адресом или именем и должна поддерживать сервер SSH (user@hostname[:destdir]).

$ devtool undeploy-target recipe target

8.16. Создание уровня рабочего пространства в другом месте

Команда devtool create-workspace создает новый уровень workspace в каталоге сборки, в котором создается файл README и каталог conf. Приведенная ниже команда создает уровень workspace в текущем рабочем уровне.

     $ devtool create-workspace

Можно создать уровень workspace в другом месте, а также изменить его имя, например devtool create-workspace /home/scottrif/new-workspace, создаст уровень new-workspace в домашнем каталоге пользователя scottrif.

8.17. Получение статуса заданий в рабочем пространстве

Команда devtool status выводит список заданий, размещенных на уровне workspace, включая пути к соответствующим внешним деревьям кода. Приведенная ниже команда показывает задание mtr_0.86.bb и путь к его файлам.

$ devtool status
mtr: /home/scottrif/poky/build/workspace/sources/mtr
     (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)

8.18. Поиск доступных заданий для целей

Команда devtool search позволяет найти доступные задания для цели по имени задания или пакета, а также по описанию и установленным файлам.

Глава 9. Справочник по OpenEmbedded Kickstart (`.wks`)

9.1. Введение

Текущая реализация Wic поддерживает только базовые команды kickstart для разделов — partition (сокращенно part) и bootloader. В новых версиях будут добавлены другие команды и опции. Использование неподдерживаемых команд ведет к непредсказуемым результатам.

В этой главе описаны доступные команды kickstart, их синтаксис и опции. Команды основаны на версиях Fedora kickstart с изменениями, учитывающими возможности Wic. Полная документация по командам доступна по ссылке.

9.2. Команда part (partition)

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

part [mntpoint] 
partition [mntpoint]

Если точка монтирования mntpoint не указана, Wic создает раздел, не монтируя его. Параметр mntpoint должен принимать одну из двух форм:

/path — например, «/», «/usr», «/home»;
swap — раздел, используемый для подкачки (swap).

Указание mntpoint приводит к автоматическому монтированию раздела. Wic обеспечивает это путем добавления записей в таблицу файловых систем (fstab) при генерации образа. Для генерации Wic корректного файла fstab нужно указать также опцию раздела —ondrive, —ondisk или —use-uuid partition как часть команды.

Программа mount должна понимать синтаксис PARTUUID, используемый с —use-uuid и не корневыми точками монтирования, включая swap. Версии этой команды в busybox в настоящее время не умеют этого.

Ниже приведен пример с точкой монтирования /. Опция —ondisk служит для указания раздела на диске sdb.

     part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024

Ниже приведен список поддерживаемых командой part (partition) опций.

—size задает минимальный размер раздела в мегабайтах целым числом без суффикса MB. Опция нужна при использовании —source.
—fixed-size задает точный размер раздела в мегабайтах и не может использоваться вместе с —size. Если собранный образ больше заданного опцией размера, возникает ошибка.
—source является опцией Wic, которая задает источник данных для заполнения раздела. Чаще всего эта опция имеет значение rootfs, но могут применяться и другие значения, отображаемые на пригодный подключаемый модуль (source plug-in, см. раздел Using the Wic Plug-Ins Interface [2]).
При использовании —source rootfs Wic создает раздел требуемого размера и заполняет его содержимым корневой файловой системы, указанным опцией -r или эквивалентом rootfs, полученным из опции -e. Тип файловой системы для создания раздела выводится из опции —fstype.

При задании —source plugin-name Wic создает раздел требуемого размера и заполняет его содержимым, которое создается заданным подключаемым модулем с использованием данных, указанных опцией -r или эквивалентом rootfs, полученным из опции -e. Содержимое и тип файловой системы зависят от плагина.

Если опция —source не применяется, команда wic создает пустой раздел, поэтому нужна опция —size для точного задания размера.
--ondisk или --ondrive задает создание раздела на определенном диске.
--fstype задает тип файловой системы для раздела (ext4, ext3, ext2, btrfs, squashfs, swap).
--fsoptions задает строку опций в произвольной форме для использования при монтировании файловой системы. Строка копируется в файл /etc/fstab установленной системы и заключается в кавычки. Если опция не задана, используется значение defaults.
—label label задает метку файловой системы (label) для раздела. Если такая метка уже применяется другой файловой системой, создается новая метка.
--active помечает раздел как активный (загрузка).
—align (кбайт) — специальная опция Wic, указывающая начало раздела на границе, кратной заданному числу.
--no-table — специальная опция Wic, резервирующая пространство для раздела без добавления записи в таблицу разделов.
--exclude-path — специальная опция Wic, исключающая указанный путь из результирующего образа. Работает только с плагином rootfs.
--extra-space — специальная опция Wic, добавляющая пространство (по умолчанию 10 Мбайт) к занятому разделом месту. Окончательный размер раздела превышает заданный параметром --size.
--overhead-factor — специальная опция Wic, умножающая размер раздела на значение опции, которое должно быть больше 1 (по умолчанию 1.3).
--part-name — специальная опция Wic, задающая имя раздела GPT.
--part-type — специальная опция Wic, задающая тип идентификатора GUID для раздела GPT. Список типов GUID можно найти на странице http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs.
--use-uuid — специальная опция Wic, заставляющая Wic генерировать случайный идентификатор GUID для раздела, используемый в конфигурации загрузчика для указания корневого раздела.
--uuid — специальная опция Wic, задающая UUID для раздела.
--fsuuid — специальная опция Wic, задающая UUID файловой системы. Можно генерировать или обновлять WKS_FILE с помощью этой опции, если заранее заданный идентификатор UUID добавлен в команду загрузки ядра в конфигурационном файле загрузчика перед запуском Wic.
--system-id — специальная опция Wic, задающая системный идентификатор раздела (1-битовое шестнадцатеричное значение с необязательным префиксом 0x.
—mkfs-extraopts задает опции для передачи утилите mkfs, в дополнение к принятым по умолчанию опциям, которые на некоторых файловых системах могут не работать. Доступные опции можно увидеть по команде wic
help kickstart.

9.3. Команда bootloader

Эта команда управляет конфигурацией загрузчика с помощью описанных ниже параметров. Функциональность загрузчика и загрузочные разделы реализуются подключаемыми модулями (—source).
Команда bootloader по сути обеспечивает способ изменения конфигурации загрузчика.

—timeout задает время ожидания (секунды) загрузчика перед выбором заданного по умолчанию варианта.
—append задает параметры ядра, добавляемые к команде syslinux APPEND или grub.
—configfile указывает пользовательский файл конфигурации для загрузчика. Если файл не находится в каталоге canned-wks, нужно указать полный путь. Этот файл переопределяет все опции загрузчика.

Глава 10. Ошибки и предупреждения тестов QA

10.1. Введение

При сборке задания система OE выполняет разные проверки QA, выдавая предупреждения и ошибки. Иногда новое задание для сборки программ не создает проблем, однако зачастую они возникают и приходится вносить изменения.

Хотя соблазнительно не обращать внимания на сообщения QA или даже отключить проверки, лучше попытаться решить обнаруженные при проверке проблемы. Эта глава посвящена сообщениям QA и содержит краткие рекомендации по устранению проблем.

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

В конце каждого сообщения указан связанный с ним тест QA (как указано в параграфе 6.56. insane.bbclass).
Список ошибок и предупреждений относится лишь к тестам QA и не включает другие возможные ошибки.
Поскольку некоторые тесты QA по умолчанию отключены, они не учтены здесь.

10.2. Ошибки и предупреждения

<packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]

Указанный пакет содержит файлы в /usr/libexec, тогда как конфигурация дистрибутива указывает другой путь к <libexecdir> (по умолчанию $prefix/libexec, но может быть измене, например, ${libdir}).

package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]

Указанный двоичный файл, созданный заданием, содержит пути загрузки динамических библиотек (rpaths) с путями сборки (такими как TMPDIR), которые некорректны для цели и могут создавать проблемы безопасности. Следует проверить опции -rpath, передаваемые компоновщику, в журнале задачи do_compile. В зависимости от используемой системы сборки, могут быть опции для полного запрета использования rpath при сборке задания.

<packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]

Указанный двоичный файл, созданный заданием, содержит пути загрузки динамических библиотек (rpaths), которые на стандартных системах просматриваются компоновщиком по умолчанию (например, /lib и /usr/lib). Такие пути не вызывают неполадок, но занимают место, будучи ненужными. В зависимости от используемой системы сборки, могут быть опции для полного запрета использования rpath при сборке задания.

<packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]

В указанных файлах пакета <packagename> были обнаружены зависимости на уровне файлов, не соответствующие явно записям в RDEPENDS. Если файлы нужны при работе, RDEPENDS в задании следует указывать пакеты, предоставляющие эти файлы.

<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]

Между указанными пакетами имеется зависимость при работе, но в задании ничто явно не указывает системе сборки OE необходимость выполнения этой зависимости. Это обычно связано с добавлением значения RDEPENDS на этапе подготовки пакета вместо того, чтобы автоматически сделать это раньше на основе содержимого пакета. В большинстве случаев в задание следует явно добавить RDEPENDS для зависимости.

non-dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]

Символьные ссылки на файлы .so, предназначенные лишь для разработки, которые нужно перенести в пакет -dev. Это может возникать при добавлении *.so* вместо *.so.* в пакеты, не относящиеся к разработке. Следует изменить FILES (возможно и PACKAGES), чтобы указанные файлы .so перешли в пакет -dev.

non-staticdev package contains static .a library: <packagename> path '<path>' [staticdev]

Файлам статической библиотеки .a следует быть в пакете -staticdev. Следует изменить FILES (возможно и PACKAGES), чтобы указанные файлы .a перешли в пакет -staticdev.

<packagename>: found library in wrong location [libdir]

Указанный файл может быть установлен в некорректно (возможно заданное жестко) место. Например, проверка будет указывать задания, которые устанавливают файлы /lib/bar.so, когда ${base_libdir} = «lib32». Другим случаем является установка заданием /usr/lib64/foo.so при ${libdir} = «/usr/lib». Возможны ложные срабатывания и в таких случаях следует добавить «libdir» в INSANE_SKIP для пакета.

non debug package contains .debug directory: <packagename> path <path> [debug-files]

Указанный пакет содержит каталог .debug, которому не следует появляться вне пакетов -dbg. Это может быть связано с добавлением пути, содержащего каталог .debug, и неявным добавлением .debug в пакет -dbg. В таких случаях следует явно добавить .debug в переменную FILES_${PN}-dbg.

Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]

По умолчанию система сборки OE проверяет тип ELF, размер слова и порядок битов во всех двоичных файлах на предмет соответствия целевой архитектуре. Отрицательный результат проверки может говорить о выборе неверного компилятора или опций. Иногда для программ (например, загрузчиков) требуется обход этого теста. Если файл, для которого указываются ошибки, относится к микрокоду, не предназначенному для выполнения в целевой операционной системе, следует добавить arch в переменную INSANE_SKIP для пакета. Помощь в обнаружении источника проблем может оказать просмотр журнала задачи do_compile в части неверных опций.

Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]

Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]

ELF binary '<file>' has relocations in .text [textrel]

Указанный двоичный файл ELF содержит перемещения (relocation) в своих разделах .text. Это влияет на производительность работы. Обычно проблему можно решить добавлением опции компилятора -fPIC или -fpic. Например, для программы, читающей при сборке переменную CFLAGS можно добавить в задание строку CFLAGS_append = » -fPIC «. Дополнительная информация о перемещениях в процессе работы доступна по ссылке.

No GNU_HASH in the elf binary: '<file>' [ldflags]

Двоичный файл, созданный при сборке задания не был скомпонован с опциями LDFLAGS, предоставленными системой сборки. Следует проверить передачу переменной LDFLAGS команде компоновщика. Для обхода проблемы в этой ситуации обычно применяется передача LDFLAGS с помощью TARGET_CC_ARCH внутри задания в форме TARGET_CC_ARCH += «${LDFLAGS}».

Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]

Указанный пакет содержит драйвер Xorg, но не имеет соответствующей зависимости ABI. Имена драйверов ABI предоставляет пакет xserver-xorg и все драйверы должны зависеть от версии ABI, с которой они были собраны. Задания для драйверов, включающие xorg-driver-input.inc или xorg-driver-video.inc получают эту версию автоматически, поэтому следует лишь явно добавить зависимости в задания для двоичных драйверов.

The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]

Каталог /usr/share/info/dir не следует включать в пакеты. Для этого следует добавить в задачу do_install или do_install_append строку rm ${D}${infodir}/dir.

Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]

Символьная ссылка указывает на каталог TMPDIR хоста сборки и будет некорректной на целевой платформе. Следует исправить ссылку, указав в ней относительный путь, либо удалить эту ссылку.

<file> failed sanity test (workdir) in path <path> [la]

Указанный файл .la содержит пути TMPDIR. Это некорректно, поскольку libtool добавляет префикс sysroot при использовании файлов.

<file> failed sanity test (tmpdir) in path <path> [pkgconfig]

Указанный файл .pc содержит пути TMPDIR/WORKDIR. Это некорректно, поскольку pkg-config добавляет префикс sysroot при доступе к файлам.

<packagename> rdepends on <debug_packagename> [debug-deps]

Имеется зависимость между указанным пакетом, не относящимся к отладке (имя пакета не имеет суффикса -dbg), и пакетом dbg. Пакеты dbg содержат отладочные символы и могут создаваться несколькими способами:

включение dbg-pkgs в IMAGE_FEATURES;
использование IMAGE_INSTALL;
как зависимость другого пакета dbg, созданного одним из предыдущих способов.

Зависимости могут добавляться автоматически в результате ошибочного включения ненужных фалов в пакет dbg (например, файл .so вместо символьной ссылки) или вручную (например, через переменную RDEPENDS).

<packagename> rdepends on <dev_packagename> [dev-deps]

Имеется зависимость между указанным пакетом, не относящимся к разработке (имя пакета не имеет суффикса -dev), и пакетом для разработки. Пакеты dev включают файлы заголовков и могут создаваться разными способами:

включение dev-pkgs в IMAGE_FEATURES;
использование IMAGE_INSTALL;
как зависимость другого пакета dev,созданного одним из предыдущих способов.

Зависимости могут добавляться автоматически в результате ошибочного включения ненужных фалов в пакет dev (например, файл .so вместо символьной ссылки) или вручную (например, через переменную RDEPENDS).

<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]

При добавлении зависимости с учетом версии в одну из переменных RDEPENDS, RRECOMMENDS, RSUGGESTS, RPROVIDES, RREPLACES, RCONFLICTSдолжны применяться лишь указанные операторы сравнения. Следует изменить значения зависимостей с учетом версий в соответствии с сообщением.

<recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path]

Журнал задачи do_compile показывает, что файлы отыскивались по путям на хосте — это неприемлемо для кросс-компиляции. Следует найти эти имена по строке «is unsafe for cross-compilation» или «CROSS COMPILE Badness».

<recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path]

Журнал задачи do_install показывает, что файлы отыскивались по путям на хосте — это неприемлемо для кросс-компиляции. Следует найти эти имена по строке «is unsafe for cross-compilation» или «CROSS COMPILE Badness».

This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>'

Журнал задачи do_configure показывает, что файлы отыскивались по путям на хосте — это неприемлемо для кросс-компиляции. Следует найти эти имена по строке «is unsafe for cross-compilation» или «CROSS COMPILE Badness».

<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]

Внутреннее соглашение системы сборки OE (иногда вынуждаемое менеджером пакетов) требует указывать имена пакетов в нижнем регистре. Если задание не следует этому или добавляются пакеты, не соответствующие соглашению, в переменную PACKAGES,выдается данное сообщение. В таких случаях следует переименовать задание или имена пакетов, включенных вPACKAGES.

<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]

Сценарий configure сообщает о непонятной опции, что может быть следствием изменения набора поддерживаемых параметров или возникновения ошибки в имени опции. Следует внимательно посмотреть вывод команды ./configure --help и журнал изменений в репозитории (change log), а затем должным образом изменить переменные EXTRA_OECONF, PACKAGECONFIG_CONFARGSили отдельные опции вPACKAGECONFIG.

Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]

Имя указанного задания (PN) присутствует в OVERRIDES. Если задание названо так, что его имя соответствует чему-либо включенному в OVERRIDES (например, PN совпадает с MACHINE или DISTRO), могут возникать неожиданные последствия. Например, назначение вида FILES_${PN} = "xyz" будет приводить к FILES = "xyz". Следует переименовать задание (или PN,если переменная задана явно) для устранения конфликта.

<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]

Некоторые переменные (RDEPENDS, RRECOMMENDS, RSUGGESTS, RCONFLICTS, RPROVIDES, RREPLACES, FILES, pkg_preinst, pkg_postinst, pkg_prerm, pkg_postrm, ALLOW_EMPTY) всегда следует устанавливать для конкретного пакета (т. е. использовать переопределением вида RDEPENDS_${PN} = "value", а не RDEPENDS = "value"). Следует исправить назначение переменных в задании.

File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]

Из созданных двоичных файлов уже вырезаны отладочные символы перед тем, как система сборки попыталась их извлечь. В разрабатываемых проектах часто вырезают отладочные символы по умолчанию. Для отладки пакетов на целевой платформе с использованием пакетов -dbg удаление символов должно быть отключено. В некоторых системах сборки это можно отключить указанием в конфигурации дополнительной опции. В иных случаях может потребоваться исправление сценариев сборки. Для этого следует насти в команде компоновки строки strip или STRIP и опции -s или -S (возможна их передача из командной строки компилятора через опцию -Wl). Запрет вырезания символов не означает их наличия в двоичных пакетах, поскольку система сборки OE выделяет эти символы в пакеты -dbg, вырезая из двоичных файлов.

<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]

Имя пакета должно указываться в переменной PACKAGES лишь 1 раз. Следует проверить переменную.

FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]

Строка // некорректна в пути Unix. Следует найти ее в переменной FILES и заменить на /.

<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]

Файлы установлены задачей do_install, но не включены в переменную FILES какого-либо задания. Такие файлы не могут пристутствовать в образе на последующих этапах сборки, поэтому нужно добавить их в переменную FILES соответствующего пакета (например, FILES_${PN} для основного пакета) или удалить файлы в конце задачи do_install, если они не нужны.

<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later

Указанную общую библиотеку предоставляют сразу <oldpackage> и <newpackage>. Это может быть следствием смены имени задания. Однако в иных случаях сообщение может означать, что ошибочно провайдером указана «приватная» версия библиотеки вместо общей. Тогда следует добавить файл библиотеки .so в переменную PRIVATE_LIBS задания, обеспечивающего приватную версию библиотеки.

10.3. Настройка и отключение проверок QA

Можно настроить проверки QA глобально, чтобы отказ конкретной проверки вызывал ошибку или предупреждение, с помощью переменных WARN_QA и ERROR_QA. Можно также отключить проверки в конкретном задании, используя INSANE_SKIP. Информация о проверках QA приведена в параграфе 6.56. insane.bbclass.

Следует помнить, что проверки QA предназначены для обнаружения имеющихся и возможных проблем в выводе пакетов, поэтому следует отключать эти проверки с осторожностью.

Глава 11. Образы

Система сборки OE включает несколько образов для разных случаев, имена которых можно указать в команде bitbake для сборки.

Сборка образов без компонент с лицензиями GPLv3, LGPLv3 или AGPL-3.0 поддерживается только для минимальных и базовых вариантов. Кроме того, для образов с компонентами, использующими лицензию, отличную от GPLv3 и подобных ей, нужно внести соответствующие изменения в файл local.conf до ввода команды BitBake для сборки.

Поместить символ комментария в начало строки EXTRA_IMAGE_FEATURES.
Установить INCOMPATIBLE_LICENSE = «GPL-3.0 LGPL-3.0 AGPL-3.0».

Посмотреть образы в в локальном репозитории poky Git можно с помощью команды ls meta*/recipes*/images/*.bb. Список поддерживаемых заданий приведен ниже.

build-appliance-image

Пример виртуальной машины, содержащей все компоненты, требуемые для запуска сборки, использующей систему сборки, а также самой системы сборки. Можно собрать и запустить образ с помощью VMware Player или VMware Workstation. Дополнительная информация приведена на странице Build Appliance сайта YP.

core-image-base

Образ с консольным интерфейсом и полной поддержкой оборудования целевой платформы.

core-image-clutter

Образ с поддержкой инструментов Clutter на основе Open GL, обеспечивающих разработку графических интерфейсов с анимацией.

core-image-full-cmdline

Образ с консольным интерфейсом и расширенной функциональностью Linux.

core-image-lsb

Образ, соответствующий спецификации LSB, требующий конфигурации дистрибутива в соответствии с LSB (например, poky-lsb). При сборке core-image-lsb без такой конфигурации образ не будет соответствовать LSB.

core-image-lsb-dev

Образ core-image-lsb с поддержкой разработки на хосте, включающий файлы заголовков и библиотеки, нужные для разработки. Образ требует конфигурации дистрибутива в соответствии с LSB (например, poky-lsb). При сборке core-image-lsb-dev без такой конфигурации образ не будет соответствовать LSB.

core-image-lsb-sdk

Образ core-image-lsb с поддержкой кросс-разработки, включающий файлы заголовков и библиотеки, нужные для формирования автономного SDK. Образ требует конфигурации дистрибутива в соответствии с LSB (например, poky-lsb). При сборке core-image-lsb-sdk без такой конфигурации образ не будет соответствовать LSB. Образ пригоден для разработки на целевой платформе.

core-image-minimal

Компактный образ, пригодный для загрузки на устройстве.

core-image-minimal-dev

Образ core-image-minimal с поддержкой разработки на хосте, включающий файлы заголовков и библиотеки, нужные для разработки.

core-image-minimal-initramfs

Образ core-image-minimal с файловой системой initramfs как частью ядра, которая позволяет более эффективно находить первую программу init (см. описание переменной PACKAGE_INSTALL).

core-image-minimal-mtdutils

Образ core-image-minimal с поддержкой утилит Minimal MTD, позволяющий пользователю взаимодействовать с подсистемой MTD в ядре для операций с flash-устройствами.

core-image-rt

Образ core-image-minimal с набором тестов и инструментов для работы в реальном масштабе времени.

core-image-rt-sdk

Образ core-image-rt с кросс-инструментами, заголовочными файлами и библиотеками для создания автономного SDK, пригодного для разработки на целевой платформе.

core-image-sato

Образ с поддержкой среды Sato для мобильных устройств. Образ поддерживает X11 с темой Sato, термина, редактор, менеджер файлов, проигрыватель и т. п.

core-image-sato-dev

Образ core-image-sato для разработки на хосте. Включает библиотеки для сборки приложений на устройстве, инструменты тестирования и профилирования, отладочные символы (прежнее название core-image-sdk).

core-image-sato-sdk

Образ core-image-sato с включением кросс-инструментов. Включает файлы заголовков и библиотеки для формирования автономного SDK, поддерживающего разработку на целевой платформе.

core-image-testmaster

базовый образ для автоматизированного тестирования, разворачиваемый на своем разделе, что позволяет развернуть тестируемый образ отдельно. Подробно описан в разделе Performing Automated Runtime Testing [2].

core-image-testmaster-initramfs

Образ initramfs, адаптированный для использования с core-image-testmaster.

core-image-weston

Простой образ Wayland с терминалом, включающий терминальные библиотеки и эталонный сборщик Weston (см. раздел Using Wayland and Weston [2]).

core-image-x11

Базовый образ X11 с терминалом.

Глава 12. Свойства

В этой главе описаны свойства машин и дистрибутивов, которые можно включить в образ, и описаны свойства образов. Свойства позволяют определить пакеты, включаемые в создаваемый образ. Дистрибутив позволяет выбрать включаемые свойства через переменную DISTRO_FEATURES, которая задается или дополняется в конфигурационном файле дистрибутива (poky.conf, poky-tiny.conf, poky-lsb.conf и т. п.). Свойства машины задаются в переменной MACHINE_FEATURES, устанавливаемой в файле конфигурации машины и задающей аппаратные возможности. Эти две переменные определяют модули ядра, утилиты и другие пакеты для включения в образ. Дистрибутив позволяет задать набор свойств машины, которые не будут включаться, если дистрибутив их не поддерживает.

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

$ cd poky
     $ git grep 'contains.*MACHINE_FEATURES.*feature'

12.1. Свойства машины

Ниже перечислены элементы, которые можно указать в MACHINE_FEATURES. Свойства не соответствуют однозначно пакетам и могут выходить за рамки простого управления пакетами. Иногда свойство может влиять на сборку нескольких заданий. Например, свойство может указывать наличие некого параметра задачи do_configure в задании. В списке свойств представлены только свойства из метаданных YP.

acpi — оборудование включает ACPI (x86/x86_64).
alsa — оборудование имеет драйверы ALSA.
apm — оборудования использует APM (или эмуляцию APM).
bluetooth — оборудование имеет встроенные элементы BT.
efi — поддержка загрузки через EFI.
ext2 — устройство HDD или Microdrive.
irda — оборудование поддерживает IrDA.
keyboard — устройство имеет клавиатуру.
pcbios — поддержка загрузки через BIOS.
pci — оборудование имеет шину PCI.
Pcmcia — оборудование имеет гнезда PCMCIA или CompactFlash.
phone — поддержка мобильных телефонов (голос).
qvga — машина имеет дисплей QVGA (320×240).
rtc — машина имеет часы RTC.
screen — устройство имеет экран.
serial — устройство имеет последовательный порт (обычно RS232).
touchscreen — устройство имеет сенсорный экран.
usbgadget — оборудование поддерживает устройства USB (гаджеты).
usbhost — оборудование поддерживает хост USB.
vfat — поддержка файловой системы FAT.
wifi — оборудование имеет встроенные элементы WiFi.

12.2. Свойства дистрибутива

Ниже представлен список свойств, которые можно установить для дистрибутива в переменной DISTRO_FEATURES.Свойства не соответствуют однозначно пакетам и могут выходить за рамки простого управления пакетами. Иногда свойство может влиять на сборку нескольких заданий. Например, свойство может указывать наличие некого параметра задачиdo_configureв задании.

Некоторые свойства дистрибутива являются и свойствами машины. Управлять такими свойствами можно на обоих уровнях (см. описание переменной COMBINED_FEATURES). В списке представлены лишь свойства из метаданных YP.

alsa — включает поддержку ALSA (при доступности устанавливаются модули ядра для совместимости с OSS).
api-documentation — включает создание документации API при сборке. Документация добавляется в архив SDK при использовании команды bitbake -c populate_sdk (раздел Adding API Documentation to the Standard SDK [7]).
bluetooth — включает поддержку bluetooth (только встроенные BT).
bluez5 — включает BlueZ версии 5 с поддержкой базовых уровней и протоколов Bluetooth. По умолчанию значение DISTRO_FEATURES включает bluetooth, что вызывает включение bluez5. Если поддержка bluez5 не нужна и достаточно bluez4, нужно задать DISTRO_FEATURES_BACKFILL_CONSIDERED = «bluez5». Установка этой переменной говорит системе сборки OE, что использование bluez5 исключается в пользу bluez4.
cramfs — включает поддержку CramFS.
directfb — включает поддержку DirectFB.
ext2 — включает инструменты для поддержки устройств с HDD/Microdrive для хранения файлов.
ipsec — включает поддержку IPSec.
ipv6 — включает поддержку IPv6.
irda — включает поддержку IrDA.
keyboard — включает поддержку клавиатуры (например, будет загружаться keymap).
ldconfig — включает поддержку ldconfig и ld.so.conf на целевой платформе.
nfs — включает поддержку клиентов NFS (для монтирования на устройстве NFS export).
opengl — включает библиотеку Open GL, обеспечивающую кроссплатформенный и многоязычный интерфейс API для плоской и трехмерной графики.
pci — включает поддержку шины PCI.
pcmcia — включает поддержку PCMCIA/CompactFlash.
ppp — включает поддержку PPP dialup.
ptest — включает сборку тестов пакетов для отдельных заданий (см. Testing Packages With ptest [2]).
smbfs — включает поддержку клиентов SMB (для монтирования каталогов Samba/Microsoft Windows).
systemd — включает поддержку менеджера инициализации systemd, который является полной заменой init и обеспечивает параллельный запуск служб, снижение нагрузки на оболочку и пр.
usbgadget — включает поддержку USB Gadget (для разных устройств USB).
usbhost — включает поддержку USB Host (подключение внешней клавиатуры, мыши, дисков и т. п.).
wayland — включает серверный протокол Wayland и библиотеку для его поддержки.
wifi — включает поддержку встроенных устройств WiFi.
x11 — включает X-сервер и библиотеки поддержки.

12.3. Свойства образа

Содержимым образов, создаваемых системой сборки OE, можно управлять с помощью переменных IMAGE_FEATURES и EXTRA_IMAGE_FEATURES,которые обычно указываются в задании для образа. Эти переменные помогают выбрать возможности из предопределенных вариантов, такие как отладка или средства разработки.

Ниже пеерчислены свойства (возможности) доступные для всех образов.

allow-empty-password позволяет входить в Dropbear и OpenSSH с именем root и другими именами без пароля.
dbg-pkgs устанавливает отладочные символы для всех пакетов, включенных в образ.
debug-tweaks делает образ пригодным для отладки (см. свойства allow-empty-password, empty-root-password, post-install-logging).
dev-pkgs устанавливает компоненты разработки (заголовочные файлы и дополнительные библиотеки) для всех пакетов в образе.
doc-pkgs устанавливает пакеты документации для всех пакетов в образе.
empty-root-password устанавливает пустой пароль для пользователя root.
package-management устанавливает средства управления пакетами и сохраняет базу данных о пакетах.
post-install-logging включает запись событий пост-установочных сценариев в файл /var/log/postinstall.log при первой загрузке образа на целевой системе. Переменная VOLATILE_LOG_DIR = no делает каталог /var/log в образе постоянным.
ptest-pkgs устанавливает пакеты ptest для всех поддерживающих ptest пакетов.
read-only-rootfs создает образ с корневой файловой системой, доступной лишь для чтения (см. раздел Creating a Read-Only Root Filesystem [2]).
splash включает вывод заставки в процессе загрузки системы. По умолчанию заставка обеспечивается пакетом psplash, который не позволяет менять свою конфигурацию. Можно использовать другую заставку, указав имя пакета (пакетов) в переменной SPLASH задания для образа или на уровне конфигурации дистрибутива.
staticdev-pkgs устанавливает статические библиотеки разработки (файлы *.a) для всех пакетов в образе.

Некоторые образы, доступные лишь при наследовании класса core-image,перечислены ниже.

hwcodecs устанавливает кодеки аппаратного ускорения.
nfs-server устанавливает сервер NFS.
perf устанавливает инструменты профилирования, такие как perf, systemtapиLTTng. Информация о работе с этими инструментами приведена в [7].
ssh-server-dropbear устанавливает Dropbear (минимальный сервер SSH).
ssh-server-openssh устанавливает сервер OpenSSH SSH с более развитыми функциями, нежели Dropbear. При наличии обоих серверов OpenSSH и Dropbear в переменной IMAGE_FEATURESпредпочтение будет отданоOpenSSH и Dropbear не будет устанавливаться.
tools-debug устанавливает средства отладки, такие как strace и gdb. Информация о работе с GDB приведена в разделе Debugging With the GNU Project Debugger (GDB) Remotely [2], а трассировка описана в [9].
tools-sdk устанавливает полный пакет SDK для работы на устройстве.
tools-testapps устанавливает инструменты тестирования устройства (например, отладки серверного экрана).
x11 устанавливает X-сервер.
x11-base устанавливает X-сервер с минимальной оболочкой.
x11-sato устанавливает X-сервер с оболочкой OpenedHand Sato.

12.4. Отключение автоматически добавляемых свойств

Иногда системе сборки OE требуются значения MACHINE_FEATURES или DISTRO_FEATURES для контроля добавленной функциональности, которую невозможно отключить. В таких случаях нужно добавлять запись дополнительного свойства в одну из указанных переменных, но это заставит разработчиков, у которых уже заданы эти переменные, добавлять новые свойства, чтобы сохранить общий уровень функциональности. Поэтому система сборки OE включает механизм автоматического отключения (backfill) добавленных свойств в имеющиеся конфигурации дистрибутива или машины. Список свойств, для которых это выполняется, можно увидеть в переменных DISTRO_FEATURES_BACKFILL и MACHINE_FEATURES_BACKFILL файла meta/conf/bitbake.conf file.

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

Ниже приведены два примера.

Свойство дистрибутива pulseaudio. Ранее поддержка PulseAudio включалась в Qt и GStreamer. Поэтому свойство добавляется автоматически через переменную DISTRO_FEATURES_BACKFILL и автоматически включается для всех дистрибутивов в файле meta/conf/bitbake.conf. Для отключения этого свойства без влияния на конфигурации других дистрибутивов, которым нужна поддержка PulseAudio, добавляется значение pulseaudio в переменную DISTRO_FEATURES_BACKFILL_CONSIDERED файла конфигурации дистрибутива. Добавление в эту переменную свойства, указанного также в DISTRO_FEATURES_BACKFILL, предотвратит добавление системой сборки этого свойства в DISTRO_FEATURES, т. е. к отключению в данном дистрибутиве.
Свойство машины rtc.Ранее поддержка часов RTC1была включена для всех целевых устройств, поэтому свойство автоматически добавлялось для всех машин через переменную MACHINE_FEATURES_BACKFILLв файле meta/conf/bitbake.conf file. Однако такие часы поддерживают не все устройства. Для таких устройств можно отключить поддержку этих часов с помощью переменной MACHINE_FEATURES_BACKFILL_CONSIDEREDв файле конфигурации машины .conf. Добавление свойства в переменную MACHINE_FEATURES_BACKFILLпредотвратит включение свойства в переменную MACHINE_FEATURES, т. е. поддержку RTC в данной машине.

1Real time clock — часы в реальном масштабе времени.

Продолжение

1Linux Standard Base.

2Дополнение частично введенных команд при нажатии клавиши Tab.

3Virtual Box Virtual Disk Image — образ виртуального диска Virtual Box.

4QEMU Copy On Write Version 2.

5Executable and Linkable Format — исполняемый и компонуемый формат.

6Node package manager — менеджер пакетов узла.

Рубрика: Linux | Комментарии отключены

Справочник по Yocto Project

Опубликовано 22.12.2019 автором Nikolai Malykh

PDF

Scott Rifenbark

Scotty’s Documentation Services, INC

<srifenbark@gmail.com>

Разрешается копирование, распространение и изменение документа на условиях лицензии Creative Commons Attribution-Share Alike 2.0 UK: England & Wales, опубликованной Creative Commons.

Этот документ основан на переводе Yocto Project Reference Manual для выпуска 2.7.1. Свежие версии оригинальных документов можно найти на странице документации Yocto Project. Размещенные там материалы более актуальны, нежели включенные в архивы пакета Yocto Project.

Глава 1. Системные требования

В этом документе приведена справочная информация для текущего выпуска Yocto Project (YP). Документ лучше изучать после знакомства с основами YP. Здесь приведены определения переменных, классов и других элементов, применяемых в YP.

Вводную информацию о YP можно найти на сайте Yocto Project Website и в разделе Yocto Project Development Environment [1].

Если вы хотите использовать YP для быстрой сборки образа, не разбираясь в деталях и концепции, работайте с документом [5]. Документация по отдельным операциям представлена в [2], а обзор и концепции YP — в [1].

Дополнительные сведения о документации YP приведены в разделе Литература.

1.1. Поддерживаемые дистрибутивы Linux

Выпуски YP тестируются со стабильными дистрибутивами Linux из приведенного ниже списка. YP может работать и с другими дистрибутивами, но проверка для них не проводилась. YP не поддерживает и не включает планов по поддержке находящихся в разработке дистрибутивов по причине их частого изменения. Приветствуются исправления (patch) и сообщения об ошибках при работе с такими дистрибутивами, но следует принимать во внимание, что основные усилия разработчиков направлены на перечисленные ниже платформы

Ubuntu 16.04 (LTS);
Ubuntu 18.04;
Fedora 28;
Fedora 29;
CentOS 7.x;
Debian GNU/Linux 8.x (Jessie);
Debian GNU/Linux 9.x (Stretch);
OpenSUSE 42.3.

Yocto Project не совместим с WSL¹ и сборочный хост не будет работать на системе WSL.

При возникновении проблем воспользуйтесь ссылкой Yocto Project Bugzilla для представления ошибки. Информация о работе с системой сбора ошибок доступна на странице YP Bugzilla wiki и в разделе Submitting a Defect Against the Yocto Project [2].

Команда YP старается сделать выпуски YP полностью совместимыми с официально поддерживаемыми дистрибутивами Linux, однако могут возникать проблемы с некоторыми дистрибутивами.

1.2. Пакеты, требуемые на сборочном хосте

Список пакетов, требуемых на сборочном хосте, может быть обширным для охвата всех сценариев сборки, используемых в YP. В этом разделе рассмотрены зависимости в соответствии с дистрибутивами Linux и функциями.

1.2.1. Ubuntu и Debian

Ниже приведен список пакетов, требуемых на сборочном хосте Ubuntu или Debian.

Пакеты для сборки образов.

$ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
xterm

Пакеты для сборки руководств YP.

$ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto

Если в вашей системе сборки установлен пакет oss4-dev, могут возникнуть проблемы при сборке для QEMU по причине установки в Debian своего файла /usr/include/linux/soundcard.h. В таких случаях можно воспользоваться одним из 2 показанных ниже решений.

1.2.2. Fedora

Ниже приведен список пакетов, требуемых на сборочном хосте Fedora Linux.

Пакеты для сборки образов.

$ sudo dnf install gawk make wget tar bzip2 gzip python3 unzip perl patch \
diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \
ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-bignum socat \
python3-pexpect findutils which file cpio python python3-pip xz python3-GitPython \
python3-jinja2 SDL-devel xterm

Пакеты для сборки руководств YP.

$ sudo dnf install docbook-style-dsssl docbook-style-xsl \
docbook-dtds docbook-utils fop libxslt dblatex xmlto

1.2.3. OpenSUSE

Ниже приведен список пакетов, требуемых на сборочном хосте openSUSE.

Пакеты для сборки образов.

$ sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \
diffstat makeinfo python-curses patch socat python3 python3-curses tar python3-pip \
python3-pexpect xz which python3-Jinja2 Mesa-libEGL1
$ sudo pip3 install GitPython libSDL-devel xterm

Пакеты для сборки руководств YP.
```
     $ sudo zypper install dblatex xmlto
```

1.2.4. CentOS

Ниже приведен список пакетов, требуемых на сборочном хосте CentOS Linux.

Пакеты для сборки образов.
```
     $ sudo yum install -y epel-release
     $ sudo yum makecache
     $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
     diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat \
     perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python34-pip xz \
     which SDL-devel xterm
     $ sudo pip3 install GitPython jinja2    
```
- Дополнительные пакеты для Enterprise Linux (т. е. epel-release) представляют собой набор программ из Fedora на RHEL/CentOS для простой установки пакетов, не включаемых в корпоративный дистрибутив Linux по умолчанию. Эти пакеты нужно устанавливать отдельно.
- Команда makecache получает дополнительные метаданные от epel-release.

Пакеты для сборки руководств YP.

     $ sudo yum install docbook-style-dsssl docbook-style-xsl \
     docbook-dtds docbook-utils fop libxslt dblatex xmlto

1.3. Требуемые версии Git, tar и Python

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

Git не ниже 1.8.3.1;
tar не ниже 1.27;
Python не ниже 3.4.0.

Если эти требования не выполняются, можно установить пакет buildtools,содержащий эти программы. Пакет можно загрузить в виде архива (tarball) или собрать самостоятельно с помощью BitBake.

1.3.1. Загрузка собранного архива `buildtools`

Загрузка и запуск подготовленного установщика buildtools обеспечивает простейший способ получить инструменты.

По ссылке http://downloads.yoctoproject.org/releases/yocto/yocto-2.7.1/buildtools/ найдите и загрузите файл *.sh.
Запустите сценарий установки, как показано ниже.
```
     $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-2.7.1.sh
```
В процессе работы сценария будут выводиться приглашения для выбора каталога установки. Можно выбрать, например, каталог /home/your-username/buildtools.
Запустите сценарий настройки среды с помощью команды
```
$ source /home/your_username/buildtools/environment-setup-i586-poky-linux
```
Здесь вам нужно будет указать реальный каталог установки и убедиться в использовании подходящего файла (например, i586 или x86-64).

После завершения сценария установки будет добавлен каталог инструментов в переменную PATH и инициализированы другие переменные окружения, нужные для работы с инструментами. В результате вы получите пригодные для работы версии Git, tar, Python и chrpath.

1.3.2. Сборка `buildtools`

Сборка и запуск своего установщика buildtools применяется лишь на сборочных хостах, где уже имеется BitBake. В этом случае сборочный хост служит для создания файла .sh и последующего выполнения этапов для его переноса и запуска на машине, не соответствующей требованиям к Git, tar и Python.

На машине с BitBake нужно организовать среду сборки с помощью установочного сценария (oe-init-build-env).
Для сборки инструментов используется команда BitBake
```
     $ bitbake buildtools-tarball
```
Переменная SDKMACHINE в файле local.conf определяет сборку для 32- или 64-битовой системы.

По завершении сборки файл .sh для установки инструментов размещается в каталоге tmp/deploy/sdk каталога сборки. В имени файла присутствует строка buildtools.
Файл .sh file следует перенести на машину, где не выполняются требования к Git, tar или Python.
На этой машине запускается сценарий .sh для установки программ. Например,
```
     $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-2.7.1.sh
```
В процессе работы сценария выводится приглашение указать каталог для установки. Например, /home/your_username/buildtools.
Запускается сценарий установки параметров окружения
```
$ source /home/your_username/buildtools/environment-setup-i586-poky-linux
```
Здесь вам нужно будет указать реальный каталог установки и убедиться в использовании подходящего файла (например, i586 или x86-64).

После завершения сценария установки будет добавлен каталог инструментов в переменную PATH и инициализированы другие переменные окружения, нужные для работы с инструментами. В результате вы получите пригодные для работы версии Git, tar, Python и chrpath.

Глава 2. Терминология YP

В этой главе приведены определения терминов, используемых в среде разработки YP.

Append Files — файлы дополнения

Файлы, добавляющие данный сборки в конец файла задания. Эти файлы называют файлами дополнения BitBake и файлами .bbappend. Система сборки OE предполагает, что для каждого файла дополнения имеется соответствующий файл задания (.bb) — эти файлы должны иметь имена, которые отличают только расширением (например, formfactor_0.0.bb и formfactor_0.0.bbappend).

Информация в файлах дополнения расширяет или переопределяет данные из файла задания с идентичным именем. Пример использования файлов дополнения приведен в разделе Using .bbappend Files in Your Layer [2].

В именах файлов добавления можно использовать шаблон % для сопоставления с именами заданий. Предположим, что файл добавления назван busybox_1.21.%.bbappend. Этот файл будет соответствовать любой версии файла задания busybox_1.21.x.bb, например

     busybox_1.21.1.bb
     busybox_1.21.2.bb
     busybox_1.21.3.bb

Использование символа % допускается лишь непосредственно перед расширением .bbappend.

BitBake

Процессор задач и планировщик, используемый системой сборки OE для создания образов (см. [4]).

Board Support Package (BSP) — пакет поддержки платы

Набор драйверов, определений и других компонент для поддержки конкретной аппаратной конфигурации [6].

Build Directory — каталог сборки

Область, используемая системой OE для сборки кода. Область создается при запуске сценария организации рабочего окружения из каталога исходных кодов (oe-init-build-env). Переменная TOPDIR указывает каталог сборки.

При создании Build Directory обеспечивается достаточная гибкость. Ниже приведены несколько примеров создания каталога сборки, в которых предполагается каталог исходных кодов poky.

Build Directory внутри Source Directory с принятым по умолчанию именем build
```
     $ cd $HOME/poky
     $ source oe-init-build-env    
```
Создание Build Directory в домашнем каталоге с именем test-builds
```
     $ cd $HOME
     $ source poky/oe-init-build-env test-builds    
```
Указание пути к каталогу и имени Build Directory. При этом должны существовать все промежуточные каталоги пути к Build Directory. Ниже показано создание каталога сборки YP-21.0.0 в имеющемся каталоге mybuilds внутри домашнего каталога

$cd $HOME
$ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-21.0.0

По умолчанию каталог сборки включает подкаталог TMPDIR, используемый для временных файлов в процессе работы. Каталог TMPDIR не может размещаться в файловой системе NFS2, поэтому каталог сборки по умолчанию не может размещаться на NFS. Однако если требуется разметить его в сети, это можно сделать, установив для переменной TMPDIR каталог локального диска в конфигурационном файле local.conf. В результате это разделяет каталоги TMPDIR и TOPDIR, которым является каталог сборки.

Build Host — сборочный хост

Система, используемая для сборки образов в среде разработки YP. Иногда называется хостом разработки.

Classes — классы

Файлы, обеспечивающие логическую инкапсуляцию и наследование, для упрощения многократного использования шаблонов общего назначения (Глава 6. Классы). Файлы классов используют расширение имен .bbclass.

Configuration File — файл конфигурации

Файлы с глобальными определениями переменных, пользовательскими переменными и данными аппаратной конфигурации. Эти файлы указывают системе OE, что нужно собрать и что включить в образ для поддержки конкретной платформы. Конфигурационный файлы используют расширение .conf. Файл conf/local.conf в каталоге сборки содержит заданные пользователем переменные, которые влияют на каждую сборку. Файл meta-poky/conf/distro/poky.conf определяет переменные конфигурации Yocto distro, используемые только при сборке с этим правилом. Файлы конфигурации машин в дереве исходных кодов определяют переменные для конкретного оборудования и используются лишь при сборке для соответствующей цели (например, файл machine/beaglebone.conf используется при сборке для плат Texas Instruments ARM Cortex-A8).

Container Layer — контейнерный уровень

Уровень, содержащий другие уровни. Примером контейнерного уровня является OE meta-openembedded, содержащий множество уровней meta-*.

Cross-Development Toolchain — инструменты кросс-разработки

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

YP поддерживает два набора инструментов для кросс-разработки:

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

Создание этого инструментария достаточно просто и автоматизировано. Информация о концепциях работы инструментария приведена в разделе Cross-Development Toolchain Generation [1], а также в документе [7].

Extensible Software Development Kit (eSDK) — расширяемый пакет для разработки программ

Специализированный пакет SDK3 для разработки приложений, позволяющий разработчикам встраивать свои библиотеки и изменения программ в образ, а также делать свой код доступным для других разработчиков [7].

Image — образ

Образ является конечным результатом процесса сборки BitBake для заданного набора заданий и связанных с ними метаданных. Образы являются двоичным выводом, предназначенным для работы на конкретном оборудовании или QEMU и применяемым для определенных задач. Список поддерживаемых YP типов образов представлен ниже (Глава 11. Образы).

Layer — уровень

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

Базовые сведения об уровнях приведены в разделе The Yocto Project Layer Model [1], а более подробная информация — в разделе Understanding and Creating Layers [2]. Уровни BSP рассмотрены в разделе BSP Layers [6].

Metadata — метаданные

Используются для создания дистрибутивов Linux и содержатся в файлах, которые система сборки OE анализирует при сборке образа. В общем случае метаданные включают задания, конфигурационные файлы и другую информацию, относящуюся к инструкциям по сборке, а также данные, управляющие тем, что создается, и влияющие на сборку. Метаданные включают команды и данные, используемые для указания используемых версий программ, места, откуда их следует загружать, и изменениях или дополнениях к этим программам (исправления или дополнительные файлы) для исправления ошибок или настройки под конкретную задачу. OpenEmbedded-Core содержит важный для работы набор проверенных метаданных.

В контексте ядра (kernel Metadata) термин относится к фрагментам конфигурации ядра и функциям, включенным в репозиторий yocto-kernel-cache Git.

OpenEmbedded-Core (OE-Core)

OE-Core — это метаданные, включающие основные задания, классы и связанные с ними файлы, которые должны быть общими для множества разных систем, производных от OE, включая YP. OE-Core представляет собой подмножество репозитория, созданного сообществом OE, которое было собрано в меньших набор проверенных заданий. Результатом стал строго контролируемый и качественный набор базовых заданий.

Эти метаданные можно просмотреть в каталоге meta Yocto Project Source Repositories.

OpenEmbedded Build System — система сборки OpenEmbedded

Система сборки в составе YP, основанная на проекте Poky, использующем BitBake для выполнения задач. В документации YP система сборки OE иногда называется просто системой сборки. При указании других систем сборки (например, на хосте или целевой платформе) они задаются явно.

Package — пакет

В контексте YP пакетом называется результат выполнения задания, созданный BitBake (выполненное задание), — обычные двоичные файлы, созданные из исходных кодов задания.

С использованием термина «пакет» связаны некоторые нюансы. Например, пакеты, упоминаемые в параграфе 1.2. Пакеты, требуемые на сборочном хосте, являются скомпилированными двоичными файлами, установка которых расширяет функциональность вашего дистрибутива Linux. Исторически в рамках YP пакетами назывались задания и некоторые переменные BitBake в результате сохранили не вполне корректные имена (например PR, PV, PE).

Package Groups — группа пакетов

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

Poky

Poky (произносится Pock-ee) является эталонным дистрибутивом для встраиваемых систем и тестирования. Возможности Poky приведены ниже.

Базовый дистрибутив для иллюстрации настройки своего дистрибутива.
Средства и способы тестирования компонент YP (т. е. Poky служит для проверки YP).
Средство для загрузки YP.

Poky не является дистрибутивом для реального применения, это просто стартовая точка для создания дистрибутива. Проект poky начинался с открытой системы, разработанной OpenedHand на основе имевшейся системы сборки OE для создания коммерчески поддерживаемой системы сборки Linux для встраиваемых систем. После покупки OpenedHand корпорацией Intel проект poky стал основой для системы сборки YP.

Recipe — задание

Набор инструкций для сборки пакетов. Задание указывает местоположение исходного кода, применяемые исправления, настройку конфигурации, параметры компиляции и т. п. Задания также указывают зависимости от библиотек или других заданий. Задание является логическим блоком выполнения, программой или образом для сборки и задается в файле .bb.

Reference Kit — эталонный комплект

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

Source Directory — каталог исходных кодов

Этот термин обозначает структуру (дерево) каталогов, созданную как локальная копия репозитория poky Git git://git.yoctoproject.org/pokyили распакованную из архива poky. Создание локальной копии репозитория poky Git рекомендуется в качестве метода организации Source Directory. Иногда для структуры используется название «каталог poky».

Система OE не поддерживает имена каталогов и файлов, содержащие пробелы, поэтому следует убедиться в их отсутствии в имени Source Directory.

Структура Source Directory содержит BitBake, документацию, метаданные и другие файлы, нужные для YP. Следовательно, Source Directory является необходимой частью YP.

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

Если вы будете создавать Source Directory из архива, имя каталога верхнего уровня также будет взято из этого архива. Например, при загрузке и распаковке архива poky-warrior-21.0.0.tar.bz2 вы получите Source Directory с корневым каталогом poky-warrior-21.0.0.

Важно понимать различия между Source Directory из архива и путем клонирования git://git.yoctoproject.org/poky. При распаковке архива вы получите копии файлов конкретного выпуска и внесенные вами изменения будут сохраняться лишь локально. При работе с локальным репозиторием poky Git вы будете иметь свежие копии файлов, а внесенные изменения можно будет представить в находящиеся в разработке ветви репозитория poky Git.

Дополнительную информацию о работе с репозиториями Git, ветвями и тегами можно найти в разделе Repositories, Tags, and Branches [1].

Task — задача

Блок выполнения в BitBake (например, do_compile, do_fetch, do_patch и т. п.).

Toaster

Web интерфейс для системы сборки OpenEmbedded, позволяющий настраивать и запускать сборку. Информация о сборке собирается и храниться в базе данных [8].

Upstream

Ссылка на исходный код или репозитории, которые не находятся в системе разработки, а расположены в области, поддерживаемой разработчиками (maintainer) исходного кода. Например, для работы с определенной частью кода его нужно сначала получить из «восходящего» источника.

Глава 3. Выпуски YP и создание стабильного выпуска

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

3.1. Основные и второстепенные выпуски

Основные выпуски YP (например, 2.7.1) выходят с интервалом около 6 месяцев в апреле и октябре каждого года. Ниже приведены несколько основных выпусков YP с кодовыми именами (см. 3.2. Кодовые имена основных выпусков).

2.2 (Morty);

2.1 (Krogoth);

2.0 (Jethro).

Временные интервалы никогда не бывают точными, но полугодовой интервал облегчает регулярные выпуски с жестким контролем качества (QA⁴) без перегрузки пользователей частой сменой выпусков. Месяцы выпуска выбраны с учетом продолжительных праздников в разных странах.

Второстепенные выпуски YP (младшая цифра) выходят нерегулярно и обычно вызваны накоплением достаточно важных изменений или улучшений последнего основного выпуска. Ниже приведены примеры второстепенных выпусков.

2.1.1;

2.1.2;

2.2.1.

Второстепенный выпуск указывает точку ветвления от основного выпуска, где был выполнен полный цикл QA и проверка содержимого новой ветви.

Могут также выпускаться исправления (patch) к стабильному выпуску по мере их появления.

3.2. Кодовые имена основных выпусков

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

Кодовое имя связывается с основным выпуском, поскольку номер выпуска YP (например, 2.7.1) может конфликтовать с данным уровнем или схемой нумерации версий компании. Кодовые имена уникальны и легко узнаваемы.

Выпуски тоже имеют номинальную версию и по этой причине в репозиториях используется кодовое имя. Информацию о выпусках и кодовых именах YP можно найти по ссылке https://wiki.yoctoproject.org/wiki/Releases.

3.3. Процесс подготовки стабильного выпуска

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

Текущая политика YP в части переноса в стабильные выпуски принимает во внимание лишь исправления ошибок и связанные с безопасностью изменения. Это означает, что обновления версии базового задания вряд ли будут приняты для стабильных выпусков. Исключением может служить наличие веских причин, таких как исправления, которые имеет смысл принять и в разрабатываемой версии.

Стабильные выпуски сопровождаются в течение года с момента публикации. Если будут обнаружены серьезные проблемы, исправления будут перенесены в прошлые выпуски независимо от их возраста. Для проблем, решения которых не были перенесены в прошлые выпуски, имеются деревья и ветви Community LTS, где участники делятся patch-файлами для прошлых выпусков. Однако эти исправления не проходят строгого контроля. Информацию о поддержке стабильных ветвей можно найти по ссылке https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance.

3.4. Тестирование и контроль качества

Частью процесса разработки и выпуска YP является контроль качества, основанный на тестировании. Стратегия тестирования позволяет команде YP проверить готовность выпуска. Кроме того, стратегия тестирования доступна для разработчиков, что позволяет вам проверить свои проекты. В этом разделе приведен обзор инфраструктуры тестирования YP. Дополнительную информацию о доступных тестах для ваших проектов можно найти в разделе Performing Automated Runtime Testing [2].

Инфраструктура тестирования и контроля качества интегрирована в проект и включает несколько частей.

bitbake-selftest — автономная команда для запуска тестирования основных частей BitBake и его сборщиков.
sanity.bbclass — автоматически включаемый класс для проверки полноты инструментов среды сборки и ошибок в базовой конфигурации (например, некорректная установка переменной MACHINE).
insane.bbclass — проверка вывода сборки на здравомыслие. Например, при сборке для платформы ARM проверяется назначение выходных двоичных файлов именно для этой платформы.
testimage.bbclass — тестирование работы созданных при сборке образов. Тесты обычно применяются с QEMU для загрузки образа и проверки его работы. Однако тест может также выполняться для машины, указанной адресом IP.
ptest запускает тесты для пакетов, созданных при сборке программ. Тесты выполняются на целевом образе.
oe-selftest тестирует вызовы BitBake. Эти тесты выполняются вне системы сборки OE. Команда oe-selftest по умолчанию запускает все тесты, но можно указать набор нужных тестов. Для использования oe-selftest на хосте нужно установить дополнительные пакеты (см. параграф 1.2. Пакеты, требуемые на сборочном хосте).

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

Основной автосборщик YP (autobuilder.yoctoproject.org) тестирует код каждого выпуска YP из репозиториев OE-Core, Poky и BitBake. Тестирование выполняется для текущего состояния ветви master и предложенных исправлений. Для исправлений тестирование обычно проходит в ветви ross/mut репозитория poky-contrib (ветвь master-under-test) или master-next в репозитории poky.

Тестирование этих общедоступных ветвей обеспечивает для всех желающих информацию о проверке предложенных вариантов архитектуры и заданий OE-Core. В тестах QA проверяются разные свойства, такие как multilib, субархитектура (например, x32, poky-tiny, musl, no-x11), bitbake-selftest, oe-selftest. Полное тестирование и проверка выпуска в Autobuilder занимает несколько часов. Тестирование выполняется в разных дистрибутивах Linux на системах QEMU, а не на реальном оборудовании. В дополнение к тестам Autobuilder команда YP QA выполняет тесты на разных платформах.

Глава 4. Переход на новые выпуски YP

В этой главе представлена информация о переходе с одного выпуска YP на другой. Дополнительные сведения можно получить из заметок (release notes) к соответствующему выпуску.

4.1. Общие вопросы

Некоторые вопросы перехода не связаны с конкретным выпуском YP и В этом разделе представлена информация, актуальная для любого перехода на новый выпуск YP.

Работа с пользовательскими заданиями

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

Вы может скорректировать все настройки в своем задании для работы с новым выпуском, однако это решение не будет оптимальным, поскольку процесс придется повторять для каждого нового выпуска, если проблемы будут возникать. Более эффективным решением будет использование файлов добавления (*.bbappend) для фиксации ваших настроек задания. Это изолирует внесенные вами изменений от основного задания и сделает процесс более контролируемым. Однако на практике использование файлов добавления удобно не всегда. Вариантом решения проблемы может быть создание нового задания или перенос прежнего на другой уровень.

Обновление файлов дополнения (Append)

Поскольку файлы добавления обычно содержат лишь пользовательские настройки, из часто не нужно настраивать для новых выпусков. Однако, если файл .bbappend относится к конкретной версии задания (т. е. в имени не используется шаблон %) и версия задания будет изменена, потребуется по меньшей мере переименовать файл добавления в соответствии с новым файлом задания. Несоответствие имени файла дополнения и задания (.bb) приведет к ошибке при анализе.

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

4.2. Переход на YP 1.3

В этом разделе рассмотрен переход на YP 1.3 с предыдущего выпуска.

4.2.1. Локальная конфигурация

Изменена переменная SSTATE_MIRRORS и файл bblayers.conf.

4.2.1.1. SSTATE_MIRRORS

Кэш общих состояний (sstate-cache), указанный переменной SSTATE_DIR, по умолчанию использует двухсимвольные имена каталогов для предотвращения проблем, связанных с чрезмерным числом файлов в одном каталоге. Кроме того, естественные пакеты sstate-cache, которые собираются для работы на сборочном хосте, будут помещаться в подкаталог, имя которого содержит идентификатор дистрибутива. Если вы копируете недавно структурированные данные sstate-cache на зеркало (локальное или удаленное), и указываете его в переменной SSTATE_MIRRORS, нужно добавлять в конце URL зеркала строку PATH, используемую BitBake перед добавлением пути к зеркалу. Например,

SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"

4.2.1.2. bblayers.conf

Уровень meta-yocto состоит из 2 частей, соответствующих дистрибутиву Poky и пакетам поддержки плат BSP⁵ — meta-yocto и meta-yocto-bsp,соответственно. При первом запуске BitBake после обновления файл conf/bblayers.conf будет обновлен с учетом этих изменений и будет выведено предложение о перезапуске для учета изменений.

4.2.2. Задания

Изменения в заданиях включают:

пробелы в функциях Python;
proto= в SRC_URI;
nativesdk;
задания для задач;
IMAGE_FEATURES;
удаленные задания.

4.2.2.1. Пробелы в функциях Python

Все функции Python должны использовать отступы из 4 пробелов. Ранее допускалось произвольное смешивание пробелов и символов табуляции, что усложняло расширение этих функций с помощью _append или _prepend с учетом того, что Python считает пробелы синтаксически значимыми. При определении или расширении функций Python (например, populate_packages, do_unpack, do_patch) в пользовательских заданиях или классах нужно использовать отступы из 4 пробелов.

4.2.2.2. proto= в SRC_URI

Все включения proto= в SRC_URI должны быть заменены на protocol=. Это относится к URI типов svn://, bzr://, hg:// и osc://, поскольку
в остальных уже используется protocol=.

4.2.2.3. nativesdk

Суффикс nativesdk сейчас реализован в виде префикса что значительно упрощает упаковочный код для заданий nativesdk. Все пользовательские задания nativesdk, которые являются перемещаемыми пакетами и естественны для SDK_ARCH, а также все ссылки нужно обновить с использованием nativesdk-* вместо *-nativesdk.

4.2.2.4. Задания для задач

Задания для задач сейчас называются группами пакетов (Package group) и переименованы — вместо task-*.bb используется packagegroup-*.bb. Имеющиеся ссылки на имена прежних задач task-* будут в большинстве случаев работать, поскольку для большинства пакетов существует путь автоматического обновления. Однако нужно будет обновить ссылки в ваших заданиях и конфигурациях, поскольку в будущих выпусках они могут уже не работать. Следует переименовать пользовательские задания task-* в to packagegroup-* и изменить их для наследования packagegroup вместо task, а также удалить все, что обрабатывалось классом packagegroup.bbclass (например, предоставление пакетов -dev и -dbg, установка переменной LIC_FILES_CHKSUM и т. п.). Дополнительная информация приведена в параграфе 6.94. packagegroup.bbclass.

4.2.2.5. IMAGE_FEATURES

Заданиям для образов, включавшим apps-console-core в переменной IMAGE_FEATURES, следует вместо этого указывать splash для включения заставки при загрузке. При сохранении apps-console-core заставка будет включаться, но с выдачей предупреждения. Свойства apps-x11-core и apps-x11-games для IMAGE_FEATURES были удалены.

4.2.2.6. Удаленные задания

В этом выпуске были удалены перечисленные ниже задания, для большинства которых маловероятны ссылки из ваших метаданных. Однако следует проверить наличие таких ссылок.

libx11-trim заменено на libx11, практически не отличающийся по размеру от современного Xorg.
xserver-xorg-lite — используйте взамен xserver-xorg, который практически не отличается по размеру, когда модули DRI и GLX не установлены.
xserver-kdrive — уже много лет не поддерживался.
mesa-xlib - больше не нужно.
galago — заменено на telepathy.
gail — функционально интегрировано в GTK+ 2.13.
eggdbus — больше не нужно.
gcc-*-intermediate — сборка реструктурирована для исключения этого этапа.
libgsmd — уже много лет не поддерживался. Функциональной заменой служит ofono.
contacts, dates, tasks, eds-tools — практически не поддерживаемый набор приложений PIM. Перемещено в meta-gnome уровня meta-openembedded.

В дополнение к перечисленным изменениям, каталог meta-demoapps был удален, поскольку содержащиеся в нем задания не поддерживались и многие из них устарели или были запрошены. Кроме того, эти задания не анализировались в принятой по умолчанию конфигурации. Многие из этих заданий уже заменены и поддерживаются в уровнях сообщества OE, таких как meta-oe и meta-gnome. Остальные можно найти в репозитории meta-extras на YP.

4.2.3. Именование ядер Linux

Схема именования двоичных файлов ядра изменена с включением переменной PE как части имени KERNEL_IMAGE_BASE_NAME ?= «${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}». Поскольку переменная PE по умолчанию не задана, двоичные файлы по умолчанию будут включать в имени два символа дефиса (—). Например, bzImage—3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin

4.3. Переход на YP 1.4

В этом разделе рассмотрен переход на YP 1.4 с предыдущего выпуска.

4.3.1. BitBake

Многострочные комментарии. Если строка комментария завершается символом \, следующая строка также будет являться комментарием. Все нарушения этого правила будут приводить к выводу предупреждений. В текст файлов с такими нарушения следует внести соответствующие правки.
Переопределение имен пакетов. Переменным, относящимся к именам пакетов во время выполнения (RDEPENDS, RRECOMMENDS, RSUGGESTS, RPROVIDES, RCONFLICTS, RREPLACES, FILES, ALLOW_EMPTY), а также функциям сценариев, связанных с установкой (pkg_preinst, pkg_postinst, pkg_prerm, pkg_postrm), всегда следует переопределять имена пакетов. Например, для основного пакета следует использовать RDEPENDS_${PN},а не простоRDEPENDS. BitBake использует более строгую проверку при анализе заданий.

4.3.2. Поведение при сборке

Код общего состояния был оптимизирован для предотвращения работы ненужных задач. Например, приведенная ниже команда больше не заполняет sysroot, поскольку это не требуется.
```
$ bitbake -c rootfs some-image
```
Вместо этого системе нужно просто извлечь содержимое выходных пакетов, заново создать пакеты и организовать корневую файловую систему. Это изменение не вызовет каких-либо проблем, если соблюдены объявленные зависимости.
Имена сканируемых каталогов. При сканировании для поиска файлов из SRC_URI система сборки использует для имен каталогов переменную FILESOVERRIDES вместо OVERRIDES. Обычно значение OVERRIDES совпадают с FILESOVERRIDES, однако при использовании дополнительного значения в OVERRIDES может потребоваться его добавление в FILESOVERRIDES, если оно уже не добавлено в переменную MACHINEOVERRIDES или DISTROOVERRIDES (Глава 13. Переменные).

4.3.3. Прокси и извлечение исходного кода

Добавлен сценарий oe-git-proxy для извлечения источников из репозиториев Git через прокси. Работа со сценарием описана в файле meta-yocto/conf/site.conf.sample.

4.3.4. Пользовательские интерфейсные файлы (изменение netbase)

Если вы создали свой файл etc/network/interfaces с помощью добавления к заданию netbase, вместо него потребуется создать файл добавления к заданию init-ifupdown, которое можно найти в каталоге meta/recipes-core/init-ifupdown дерева исходных кодов (см. раздел Using .bbappend Files [2]).

4.3.5. Удаленная отладка

Поддержка удаленной отладки с использованием Eclipse IDE выделена в свойство образа (eclipse-debug), которое соответствует группе пакетов packagegroup-core-eclipse-debug. Ранее отладка включалась через свойство tools-debug из группы packagegroup-core-tools-debug.

4.3.6. Переменные

SANITY_TESTED_DISTROS использует идентификатор дистрибутива, состоящий из идентификатора хоста, за которым следует идентификатор выпуска. Ранее переменная SANITY_TESTED_DISTROS содержала поле описания. Например, значение Ubuntu 12.10 становится Ubuntu-12.10. Это изменение не затронет вас, если переменная не задавалась или содержала пустое значение («»).
SRC_URI. Каталоги ${PN}, ${PF}, ${P} и FILE_DIRNAME исключены из принятого по умолчанию значения переменной FILESPATH, которая служит для указания пути поиска файлов, заданных в SRC_URI. Если ваши задания используют указанные каталоги нужно внести изменения в задание или переместить файлы. Часто используемые каталоги включены в переменные ${BP}, ${BPN} и files, которые сохранены в принятом по умолчанию значении FILESPATH.

4.3.7. Управление пакетами целевой платформы с помощью RPM

Управление пакетами в процессе работы разрешено и используется механизм RPM. Вместо Zypper устанавливается пакет Smart для загрузки программ, контроля зависимостей и обновления. Информация о работе со Smart выводится по команде smart —help.

4.3.8. Перенос заданий

Перечисленные ниже задания были перемещены, поскольку они больше не используются в OpenEmbedded-Core.

clutter-box2d на уровень meta-oe.
evolution-data-server на уровень meta-gnome.
gthumb на уровень meta-gnome.
gtkhtml2 на уровень meta-oe.
gupnp на уровень meta-multimedia.
gypsy на уровень meta-oe.
libcanberra на уровень meta-gnome.
libgdata на уровень meta-gnome.
libmusicbrainz на уровень meta-multimedia.
metacity на уровень meta-gnome.
polkit на уровень meta-oe.
zeroconf на уровень meta-networking.

4.3.9. Удаления и переименования

evieext удалено по причине удаления из xserver в 2008 г.
Gtk+ DirectFB удалено по причине исключения из Gtk+ начиная с версии 2.18.
libxfontcache, xfontcacheproto удалены по причине удаления из сервера Xorg в 2008 г.
libxp, libxprintapputil, libxprintutil, printproto удалены по причине удаления сервера XPrint из Xorg в 2008 г.
libxtrap, xtrapproto удалены по причине отказа от этой функциональности.
Ядро linux-yocto 3.0 заменено ядром linux-yocto 3.8, ядра linux-yocto 3.2 и linux-yocto 3.4 сохранены в выпуске.
lsbsetup удалено, поскольку функциональность обеспечивается lsbtest.
matchbox-stroke удалено, поскольку служило лишь для проверки концепции.
matchbox-wm-2, matchbox-theme-sato-2 удалены, поскольку больше не поддерживаются. Однако matchbox-wm и matchbox-theme-sato сохранены.
mesa-dri переименовано в mesa.
mesa-xlib удалено по причине бесполезности.
mutter удалено по причине ненужности.
orinoco-conf удалено, поскольку устарело.
update-modules удалено, поскольку больше не применяется. Сценарии postinstall и postrm для модулей ядра работают без этого сценария.
web удалено, поскольку больше не поддерживаются и заменено на web-webkit.
xf86bigfontproto удалено по причине исключения из разработки в 2007 г. Сейчас применяется xf86bigfontproto.
xf86rushproto удалено, поскольку зависимость от xserver была ошибочной и удалена в 2005 г.
zypper, libzypp, sat-solver удалены и функционально заменены на Smart (python-smartpm) при использовании пакетов RPM и включенном на целевой платформе менеджере пакетов.

4.4. Переход на YP 1.5

В этом разделе рассмотрен переход на YP 1.5 с предыдущего выпуска.

4.4.1. Изменения зависимостей для сборочного хоста

Система сборки OE предъявляет приведенные ниже требования к программам сборочного хоста.

Python 2.7.3 или выше;
Tar 1.24 или выше;
Git 1.7.8 или выше;
исправленная версия make при использовании 3.82 (применяется в большинстве дистрибутивов с make 3.82).

Если в дистрибутиве Linux на сборочном хосте нет указанных версий программ, можно воспользоваться архивом Buildtools, включающим эти программы (см. параграф 1.3. Требуемые версии Git, tar и Python).

4.4.2. `atom-pc` BSP

Эталонный аппаратный пакет BSP для atom-pc заменен BSP genericx86. Он не обязательно будет работать на всех системах x86, но пригоден для работы на большинстве систем, где работал atom-pc. Кроме того, добавлен BSP genericx86-64 для 64-битовых систем Atom.

4.4.3. BitBake

BitBake теперь поддерживает оператор _remove, что потребует переименовать все элементы (функции, переменные) в пространстве задания, содержащие _remove_ или заканчивающиеся _remove, для предотвращения неожиданного поведения.
Удален глобальный (global) метод извлечения (pool) для BitBake, который был практически бесполезен и приводил к конфликтам с заданиями, содержащими функции с таким же именем.
Удален backend-сервер none, поскольку по умолчанию уже давно применяется сервер process.
Удален сценарий bitbake-runtask.
Переменные ${P} и ${PF} больше не добавляются по умолчанию в переменную PROVIDES файла bitbake.conf. Эти зависимые от версии элементы PROVIDES применялись редко и попытка использовать их может приводить к одновременной сборке двух версий в результате используемого в BitBake метода контроля зависимостей.

4.4.4. Предупреждения QA

При установке значений ERROR_QA или WARN_QA в вашей конфигурации следует убедиться, что там указаны все проблемы, которые вы хотите видеть. В предыдущих выпусках YP была ошибка, в результате которой объекты, не указанные в ERROR_QA или WARN_QA, считались предупреждениями и некоторые важные элементы не включались по умолчанию в WARN_QA. Проверки QA описаны в параграфе 6.56. insane.bbclass.
Добавлена проверка установки /usr/share/info/dir. В вашем задании следует удалить этот файл в задаче do_install, если его устанавливает команда make install.
При использовании класса buildhistory проверка возврата версии пакетов выполняется стандартной процедурой QA. Если вы изменили значение ERROR_QA или WARN_QA и по-прежнему хотите выполнять эту проверку, следует добавить значение version-going-backwards переменной (см. параграф 6.56. insane.bbclass).

4.4.5. Изменение схемы каталогов

Выходные файлы установщика SDK имеют имена, включающие имя образа и архитектуру через переменную SDK_NAME.
Образы и связанные с ними файлы устанавливаются в каталог, определяемый машиной, а не в родительский каталог с выходными файлами для разных машин. Переменная DEPLOY_DIR_IMAGE по-прежнему указывает каталог с образами для конкретного значения MACHINE и ее следует применять везде, где нужно указывать этот каталог. Сценарий runqemu теперь использует эту переменную для поиска образов и двоичных файлов ядра и будет применять BitBake для определения каталога. Дополнительно можно установить переменную DEPLOY_DIR_IMAGE во внешней среде.
При включенном классе buildhistory его вывод будет записываться в каталог сборки, а не в TMPDIR. Это позволяет удалить TMPDIR с сохранением истории. Кроме того, данные для создаваемых SDK разделены по IMAGE_NAME.
Данные pkgdata, создаваемые в процессе упаковки, сжаты до одного каталога, определяемого машиной. Этот каталог размещается в sysroots и использует определяемое машиной имя (tmp/sysroots/machine/pkgdata).

4.4.6. Сокращенные значения Git `SRCREV`

BitBake сокращает выпуски из репозиториев Git в переменной SRCPV с обычных 40 до 10 для удобочитаемости в именах файлов и каталогов. Это изменение не должно создавать проблем в контексте, где применяются эти выпуски, поскольку вероятность конфликтов очень мала. Совпадение значений в разном контексте проблем не вызывает.

4.4.7. `IMAGE_FEATURES`

Значение IMAGE_FEATURES сейчас проверяется, чтобы предотвратить добавление непригодных элементов. Некоторые пользователи ошибочно добавляют имена пакетов в эту переменную вместо использования IMAGE_INSTALL для добавления пакетов в образ. Пригодное значение IMAGE_FEATURES выводится из определений PACKAGE_GROUP, COMPLEMENTARY_GLOB и нового флага validitems в IMAGE_FEATURES. Изменение validitems позволяет добавить свойства если они не включены двумя предыдущими механизмами.
Ранее отмененный элемент IMAGE_FEATURES apps-console-core больше не поддерживается. Если нужно включить экран заставки, добавьте splash в переменную IMAGE_FEATURES(это все, что делал элементapps-console-core).

4.4.8. `/run`

Был добавлен каталог /run в соответствии с Filesystem Hierarchy Standard 3.0. Последствия этого описаны на сайте. Изменение также привело к изменению заданий, устанавливающих файлы в каталог (рекомендации по внесению изменений доступны по ссылке.

4.4.9. Удаление базы данных менеджера пакетов из заданий для образов

Образcore-image-minimal больше не добавляет remove_packaging_data_files в переменную ROOTFS_POSTPROCESS_COMMAND. Это добавление происходит автоматически при отсутствии package-management в IMAGE_FEATURES. Если у вас есть задания с таким добавлением, нужно удалить соответствующие строки, поскольку они больше не нужны и могут создавать проблемы при выполнении пост-установочных сценариев.

4.4.10. Повторная сборка образов только при наличии изменений

Задача do_rootfs и другие задачи, связанные с созданием образов, больше не помечаются как nostamp, поэтому будут выполняться повторно лишь при наличии реальных изменений на их входе. В прежних выпусках система OE всегда заново собирала образ по запросу, е не по необходимости.

4.4.11. Задания для задач

Ранее отмененный класс task.bbclass удален. Для заданий, наследовавших этот класс следует заменить task-* на packagegroup-* и наследовать класс packagegroup.

4.4.12. BusyBox

Пакет BusyBox разделен на два двоичных исполняемых файла, один из которых использует для тех компонент, где это требуется, а второй служит для остальных задач. Такое разделение сделало возможной оптимизацию, которая исключает задание tinylogin, как было рекомендовано разработчиками. Расщепление можно отключить, установив значение 0 для переменной BUSYBOX_SPLIT_SUID.

4.4.13. Автоматизированное тестирование образов

Добавлена новая модель автоматизированного тестирования образа с использованием класса testimage.bbclass взамен старой схемы imagetest-qemu. Автоматизированное тестирование образов рассмотрено в разделе Performing Automated Runtime Testing [2].

4.4.14. История сборки

В файле installed-package-sizes.txt сейчас записываются размеры установленных файлов каждого пакета, а не размер сжатого архива.
В графах зависимостей (depends*.dot) используются реальные имена пакетов без замены символов дефиса, точек, знаков + и символов подчеркивания.
В утилитах buildhistory-diff и buildhistory-collect-srcrevs улучшена обработка параметров командной строки, которые можно посмотреть с помощью опции —help.

Работа с историей сборок описана в разделе Maintaining Build Output Quality [2].

4.4.15. `udev`

udev больше не приводит автоматически в udev-extraconf через переменную RRECOMMENDS, поскольку это изначально предполагалось необязательным. Если нужны дополнительные правила, используйте udev-extraconf для своего образа.
udev больше не приводит в pciutils-ids или usbutils-ids через переменную RRECOMMENDS. Они не нужны и их удаление экономит около 350 кбайт.

4.4.16. Удаленные и переименованные задания

Удалено ядро linux-yocto 3.2.
libtool-nativesdk переименовано с nativesdk-libtool.
Удалено tinylogin с заменой на suid-часть Busybox (см. параграф 4.4.12. BusyBox).
external-python-tarball переименован в buildtools-tarball.
web-webkit удален с заменой на midori.
imake удалено за ненадобностью.
transfig-native удалено за ненадобностью.
anjuta-remote-run удалено. Интеграция с Anjuta IDE не поддерживается уже несколькими выпусками.

4.4.17. Прочие изменения

run-postinsts является базовым.
Из base-files удалены ненужные каталоги.
alsa-state обеспечивает по умолчанию пустой файл asound.conf.
classes/image гарантирует для BAD_RECOMMENDATIONS заранее переименованных пакетов.
classes/rootfs_rpm реализует BAD_RECOMMENDATIONS для RPM.
systemd — удаляется systemd_unitdir, если systemd нет в DISTRO_FEATURES.
systemd — удаляется каталог init.d, если имеется файл инициализации systemd и sysvinit не является свойством дистрибутива.
libpam отвергает все службы для записей OTHER.
image.bbclass — перемещено runtime_mapping_rename для предотвращения конфликтов с multilib (см. YOCTO #4993 ).
linux-dtb использует систему сборки ядра для генерации файлов dtb.
kern-tools переключен с guilt на новый инструмент kgit-s2q.

4.5. Переход на YP 1.6

В этом разделе рассмотрен переход на YP 1.6 с предыдущего выпуска.

4.5.1. Класс `archiver`

Класс archiver был переписан с упрощением конфигурации. См. раздел Maintaining Open Source License Compliance During Your Product’s Lifecycle [2].

4.5.2. Изменения в пакетах

Задание binutils больше не создает пакет binutils-symlinks и применяется update-alternatives при обработке предпочтительного варианта binutils для целевой платформы.
Утилиты tc (управление трафиком) выделены из пакета iproute2 и помещены в пакет iproute2-tc.
Схемы gtk-engines перенесены в отдельный пакет gtk-engines-schemas.
Изменен суффикс архитектуры для пакетов armv7a,который теперьдля пакетов с оптимизацией имеет значение t2, как и должно быть. Этот суффикс не применялся в выпуске 1.5. Результатом является изменение имен архитектуры для пакетов.

4.5.3. BitBake

В следующих параграфах рассмотрены изменения в BitBake.

4.5.3.1. Требование к соответствию ветвей для сборщика Git

При извлечении исходных кодов из репозитория Git с использованием переменной SRC_URIпрограмма BitBake будет сравнивать значение SRCREV с ветвью. Для указания ветви можно использовать приведенную ниже форму.

SRC_URI = "git://server.name/repository;branch=branchname"

Если ветвь не задана, BitBake будет обращаться к принятой по умолчанию ветви master.

Если нужно обойти проверку (например, при извлечении версии по тегу, не относящемуся к ветвям), можно добавить «;nobranch=1» в конце URL в переменной SRC_URI.

4.5.3.2. Подстановки определений Python

BitBake включал некоторые устаревшие определения Python в удаленном модуле bb,вместо которых следует применять указанные ниже аналоги.

bb.MalformedUrlзаменяетсяbb.fetch.MalformedUrl.
bb.encodeurlзаменяетсяbb.fetch.encodeurl.
bb.decodeurlзаменяется bb.fetch.decodeurl
bb.mkdirhierзаменяетсяbb.utils.mkdirhier.
bb.movefileзаменяетсяbb.utils.movefile.
bb.copyfileзаменяетсяbb.utils.copyfile.
bb.whichзаменяетсяbb.utils.which.
bb.vercmp_stringзаменяетсяbb.utils.vercmp_string.
bb.vercmpзаменяетсяbb.utils.vercmp.

4.5.3.3. Сборщик SVK

Сборщик SVK исключен из BitBake.

4.5.3.4. Перенаправление консольного вывода ошибок

Консольный интерфейс BitBake будет направлять ошибки вывода на устройство stderr вместо stdout. Поэтому при использовании конвейеров, перенаправляющих вывод bitbake,и желании видеть ошибки, нужно добавить2>&1 (или что-то похожее) в конце командной строки bitbake.

4.5.3.5. Переопределения `task-taskname`

Переопределенияtask-taskname скорректированы так, что задачи, чьи имена содержат символы подчеркивания были переопределены в заменой этих символов дефисами для обеспечения корректной работы. Например, задача do_populate_sdk переопределена как task-populate-sdk.

4.5.4. Изменения переменных

Ниже указаны измененные переменные. Описаниям переменных системы сборки посвящена Глава 13. Переменные.

4.5.4.1. `TMPDIR`

ПеременнаяTMPDIR больше не может указывать файловые системы NFS, поскольку они не обеспечивают блокировки POSIX и согласованности inode, что может вызывать проблемы. Проверка выполняется при запуски и выводится сообщение об ошибке, если TMPDIR указывает NFS.

4.5.4.2. `PRINC`

Переменная PRINC устарела и будет вызывать предупреждения в процессе сборки. Для инкрементирования при изменениях следует использовать переменную PR. Дополнительная информация приведена в разделе Working With a PR Service [2].

4.5.4.3. `IMAGE_TYPES`

Опция sum.jffs2 для IMAGE_TYPES заменена опцией jffs2.sum, с сохранением порядка обработки.

4.5.4.4. `COPY_LIC_MANIFEST`

Для включения переменной COPY_LIC_MANIFEST теперь используется значение 1.

4.5.4.5. `COPY_LIC_DIRS`

Для включения переменнойCOPY_LIC_DIRS теперь используется значение 1.

4.5.4.6. `PACKAGE_GROUP`

Переменная PACKAGE_GROUP переименована в FEATURE_PACKAGES,чтобы точнее отражать ее назначение. ПеременнуюPACKAGE_GROUP можно использовать, но система сборки OE будет выдавать предупреждения.

4.5.4.7. Поведение команд предварительной и пост-обработки

Указанные ниже команды ожидают списка разделенных точками с запятой переменных, а не произвольных команд.

     ROOTFS_PREPROCESS_COMMAND
     ROOTFS_POSTPROCESS_COMMAND
     SDK_POSTPROCESS_COMMAND
     POPULATE_SDK_POST_TARGET_COMMAND
     POPULATE_SDK_POST_HOST_COMMAND
     IMAGE_POSTPROCESS_COMMAND
     IMAGE_PREPROCESS_COMMAND
     ROOTFS_POSTUNINSTALL_COMMAND
     ROOTFS_POSTINSTALL_COMMAND

Для перехода можно просто «обернуть» команды в функции командного процессора (shell) и затем вызывать функции, как показано ниже.

     my_postprocess_function() {
        echo "hello" > ${IMAGE_ROOTFS}/hello.txt
     }
     ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "

4.5.5. Тестирование пакетов (ptest)

Тестирование пакетов (ptest) встроено, но по умолчанию не устанавливается. Работа с тестами описана в разделе Testing Packages with ptest [2], а класс ptest — в параграфе 6.104. ptest.bbclass.

4.5.6. Изменение сборки

Раздельные каталоги для сборки и исходных кодов разрешены по умолчанию для отдельных заданий, где это известно («белый список»), а также для всех заданий, наследующих класс cmake. В будущих выпусках класс autotools будет разрешать также отделение каталога сборки по умолчанию. Программы сборки заданий на основе autotools, которые не могут работать с отдельным каталогом сборки следует изменить, чтобы они могли наследовать класс autotools-brokensep вместо autotools или autotools_stageclasses.

4.5.7. `qemu-native`

Заданиеqemu-native сейчас собирается по умолчанию без графического интерфейса на базе SDL. Для включения графического интерфейса в файле local.conf должны быть приведенные ниже строки⁶.

     PACKAGECONFIG_pn-qemu-native = "sdl"
     ASSUME_PROVIDED += "libsdl-native"

4.5.8. `core-image-basic`

Образcore-image-basic переименован в core-image-full-cmdline,а группаpackagegroup-core-basic — в packagegroup-core-full-cmdline.

4.5.9. Лицензирование

Файл LICENSE верхнего уровня изменен для более точного описания лицензий различных компонент OE-Core без изменения самого лицензирования. Обычно это изменение не вызывает побочных эффектов. Однако некоторые задания указывают этот файл в LIC_FILES_CHKSUM (как ${COREBASE}/LICENSE), поэтому нужно изменить сопровождающую контрольную сумму 3f40d7994397109285ec7b81fdeb3b58 на 4d92cd373abda3937c2bc47fbc49d690. Лучше указывать в LIC_FILES_CHKSUM файл, описывающий лицензию, распространяемую с исходным кодом для сборки задания, а не ${COREBASE}/LICENSE.

4.5.10. Опции `CFLAGS`

Опция -fpermissive удалена из принятого по умолчанию значение CFLAGS. Это нужно учитывать в заданиях, где возникает отказ при сборке без этой опции — задания нужно изменить для устранения ошибок, сообщаемых компилятором, или добавить опцию -fpermissive в переменную CFLAGS для этого задания.

4.5.11. Типы вывода пользовательских образов

Пользовательские типы образов, указанные в переменной IMAGE_FSTYPES, должны объявлять свои зависимости (при наличии) через новую переменную IMAGE_TYPEDEP.

4.5.12. Задачи

Задача do_package_write удалена за ненадобностью.

4.5.13. Поставщик `update-alternative`

Принятый по умолчанию поставщик update-alternatives сменен с opkg на opkg-utils,что позволило решить некоторые проблемы с закольцованными зависимостями. Используемый при работе пакет (runtime) update-alternatives-cworth переименован в update-alternatives-opkg.

4.5.14. Переопределение `virtclass`

Переопределения virtclass устарели и взамен используются эквиваленты (например, virtclass-native вместо class-native).

4.5.15. Удаленные и переименованные задания

packagegroup-toolset-native больше не применяется.
linux-yocto-3.8 — поддержка ядра Linux yocto 3.8 исключена, ядра 3.10 и 3.14 добавлены как задания linux-yocto-3.10 и linux-yocto-3.14.
ocf-linux функционально заменено заданием cryptodev-linux.
genext2fs больше не используется системой сборки и не поддерживается в восходящих разработках.
js — древняя версия движка Mozilla javascript, которая больше не применяется.
zaurusd перенесено на уровень meta-handheld.
eglibc 2.17 заменено заданием eglibc 2.19.
gcc 4.7.2 заменено новым стабильным gcc 4.8.2.
external-sourcery-toolchain поддерживается на уровне meta-sourcery.
linux-libc-headers-yocto 3.4+git — сейчас по умолчанию применяется the linux-libc-headers версии 3.10.
meta-toolchain-gmae отменено.
packagegroup-core-sdk-gmae отменено.
packagegroup-core-standalone-gmae-sdk-target отменено.

4.5.16. Удаленные классы

module_strip;
pkg_metainfo;
pkg_distribute;
image-empty.

4.5.17. Эталонные BSP

Эталонный пакет BeagleBoard ARM (beagleboard) заменен BeagleBone (beaglebone).
Эталонный пакет RouterStation Pro MIPS (routerstationpro) заменен EdgeRouter Lite (edgerouter).

Прежние эталонные BSP для машин beagleboard и routerstationpro сохранены на уровне meta-yocto-bsp-old в дереве исходных кодов репозитория http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/.

4.6. Переход на YP 1.7

В этом разделе рассмотрен переход на YP 1.7 с предыдущего выпуска.

4.6.1. Изменение опций QEMU `PACKAGECONFIG` в файле `local.conf`

Задание QEMU сейчас применяет множество опций PACKAGECONFIG для управления дополнительными возможностями. Используемый для задания принятых по умолчанию значений этих опций требует изменения имеющегося файла local.conf с целью добавления PACKAGECONFIG для qemu-native и nativesdk-qemu вместо их установки. Иными словами, для добавления графического вывода в QEMU следует включить в файл local.confприведенные ниже строки

     PACKAGECONFIG_append_pn-qemu-native = " sdl"
     PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"

4.6.2. Минимальная версия Git

Сейчас требуется версия Git не ниже 1.7.8, поскольку сборщику Git нужна опция --list. Как обычно, если сборочный хост не соответствует требованиям, можно загрузить и установить архив buildtools(см. параграф 1.3. Требуемые версии Git, tar и Python.

4.6.3. Изменение класса autotools

По умолчанию применяется отдельный каталог сборки. Класс autotools изменен для работы с каталогом сборки (B), отделенным от дерева исходных кодов (S). Это указывается как B != Sили сборка вне дерева.

Если собираемая программа уже позволяет сборку вне дерева, ничего изменять не нужно. Если же программа не поддерживает такой сборки, нужно ее исправить соответствующим образом или изменить задание для наследования класса autotools-brokensep вместо autotools или autotools_stage.
Опция --foreign больше не передается automake при работе autoconf. Эта опция говорит automake,что определенный пакет не соответствует стандартамGNU и поэтому не следует ожидать распространения в нем таких файлов как ChangeLog, AUTHORSи т. п. Поскольку большинство программ уже говорят automake,что они сами включают режимforeign, эта опция стала ненужной. Однако некоторые задания придется все-таки изменить. Это легко сделать, указав в файле configure.ac передачу foreign в AM_INIT_AUTOMAKE().

4.6.4. Отмена сценариев настройки конфигурации

В некоторых заданиях, упаковывающих двоичные сценарии настройки, эти сценарии отключены по причине возникновения ошибок при подстановке путей. Программам, связанным с библиотеками, использующими такие сценарии, следует применять более надежный пакет pkg-config. Список заданий, измененных в этой версии (и их сценариев настройки) включает directfb (directfb-config), freetype (freetype-config), gpgme (gpgme-config), libassuan (libassuan-config), libcroco (croco-6.0-config), libgcrypt (libgcrypt-config), libgpg-error (gpg-error-config), libksba (ksba-config), libpcap (pcap-config), libpcre (pcre-config), libpng (libpng-config, libpng16-config), libsdl (sdl-config), libusb-compat (libusb-config), libxml2 (xml2-config), libxslt (xslt-config), ncurses (ncurses-config), neon (neon-config), npth (npth-config), pth (pth-config), taglib (taglib-config). В дополнение к этому была добавлена поддержка pkg-config в некоторые задания из этого списка, если пакет еще не включал ее.

4.6.5. Замена `eglibc 2.19` на `glibc 2.20`

Поскольку eglibc и glibc уже довольно близки, замена не должна потребовать существенных изменений в программах, связанных с eglibc. Однако в glibc 2.20 внесено множество мелких изменений, которые могут потребовать исправлений в ряде программ (например, удаление макроса тестирования свойств _BSD_SOURCE). Для glibc 2.20 требуется ядро Linux версии 2.6.32 или выше. Дополнительная информация об изменениях в glibc 2.20 доступна по ссылке.

4.6.6. Автоматическая загрузка модулей ядра

Переменные module_autoload_* отменены и вместо них следует использовать новую переменную KERNEL_MODULE_AUTOLOAD. Переменные module_conf_* должны сейчас применяться вместе с новой переменной KERNEL_MODULE_PROBECONF. Эти новые переменные не требуют указания имени модуля как части имени переменной, что не только упрощает использование, но и позволяет аккуратно встраивать значения этих переменных в подписи задач и активизировать повторное выполнение задач при появлении изменений. Следует заменить все включения module_autoload_* на KERNEL_MODULE_AUTOLOADи добавить все модули, для которых заданы переменные module_conf_*, в KERNEL_MODULE_PROBECONF.

4.6.7. Изменения проверки качества (QA)

Добавлены проверки file-rdeps и build-deps для контроля соблюдения зависимостей (например, пакетов, содержащих сценарии, которым требуется /bin/bash) и корректности указания зависимостей при сборке (Глава 10. Ошибки и предупреждения тестов QA).
Проверка качества пакетов выполняется новой задачей do_package_qa, а не do_package task. Это изменение не должно вызывать проблем за исключением сложных пользовательских заданий, которые отключают задачу упаковки, помечая ее как noexec. Для таких пакетов нужно отключать задачу do_package_qa.
Файлы, переписанные при выполнении задачи do_populate_sysroot, теперь вызывают ошибку, а не предупреждение. Заданиям не следует переписывать файлы, записанные в sysroot другими заданиями, и при наличии таких заданий их следует должным образом изменить.

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

4.6.8. Удаленные задания

x-load заменено U-boot SPL для всех Cortex TI SoC. Для более старых плат следует использовать уровень meta-ti.
ubootchart устарело. Добавлено задание bootchart2, служащее функциональной заменой.
Linux-yocto 3.4 — поддержка ядра linux-yocto 3.4 прекращена, поддержка ядер 3.10 и 3.14 сохранена, добавлено ядро 3.17.
eglibc заменено на glibc (см. параграф 4.6.5. Замена eglibc 2.19 на glibc 2.20).

4.6.9. Прочие изменения

Функции записи истории сборки теперь создает вместо build-id файл build-id.txt, который включает полный заголовок сборки, выводимый BitBake при старте. Имеет смысл удалить старые файлы build-id из имеющихся репозиториев сборки для предотвращения путаницы. Функция истории сборки описана в разделе Maintaining Build Output Quality [2].

4.7. Переход на YP 1.8

В этом разделе рассмотрен переход на YP 1.8 с предыдущего выпуска.

4.7.1. Удаленные задания

owl-video функционально заменено gst-player.
gaku функционально заменено gst-player.
gnome-desktop сейчас доступно в meta-gnome и отдельное задание не нужно.
gsettings-desktop-schemas сейчас доступно в meta-gnome и отдельное задание не нужно.
python-argparse — модуль уже предоставляется в используемом по умолчанию дистрибутиве Python в пакете python-argparse, поэтому отдельное задание уже не нужно.
telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control перенесены с meta-oe и поэтому больше не нужны заданиям из OpenEmbedded-Core.
linux-yocto_3.10 и linux-yocto_3.17 — поддержка linux-yocto 3.10 и 3.17 прекращена. Ядро 3.14 поддерживается и добавлено ядро 3.19.
poky-feed-config-opkg устарело и больше не требуется. Вместо него применяется distro-feed-config их meta-oe.
libav 0.8.x — сейчас используется libav 9.x.
sed-native больше не нужно. Предполагается обеспечение рабочей версии sed дистрибутивом хоста.

4.7.2. Выбор BlueZ 4.x или 5.x

Имеется встроенная поддержка BlueZ 5.x предпочтительная по сравнению с используемой по умолчанию 4.x. Для использования BlueZ 5.x достаточно добавить bluez5 в переменную DISTRO_FEATURES. Если ранее выбор был включен в файл добавления (*.bbappend), его можно удалить. Кроме того, был добавлен класс bluetooth для более удобного выбора подходящей поддержки bluetooth в задании. Для использования этого класса в задании добавьте строки по приведенному ниже образцу.

inherit bluetooth
PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}
PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"

4.7.3. Изменение сборки ядра

Процесс сборки ядра был изменен, чтобы поместить исходные коды в общую рабочую область и отделить элементы сборки (artifact) в дереве исходных кодов. В теории пути перехода были предоставлены для наиболее распространенных вариантов заданий для сборки ядер, но это может работать не во всех случаях. В частности нужно обеспечить корректность использования переменных ${S} (исходные коды) и ${B} (элементы сборки) в таких функциях, как do_configure и do_install. Для заданий, не наследующих kernel-yocto и не включающих linux-yocto.inc, можно использовать файл linux.inc уровня meta-oe для внесения всех требуемых изменений. Для справки можно воспользоваться ссылкой на обновление файла linux.inc для уровня meta-oe.

Задания, основанные на исходном коде ядра и не наследующие класс module, могут требовать явного указания зависимостей в задаче ядра do_shared_workdir. Например, do_configure[depends] += «virtual/kernel:do_shared_workdir».

4.7.4. Запрет SSL 3.0 в OpenSSL

SSL 3.0 сейчас отключен при сборке OpenSSL. Это позволяет избежать уязвимости POODLE vulnerability. Если нужно все-таки включить SSL 3.0, это можно сделать в файле добавления (*.bbappend) для задания openssl, удалив -no-ssl3 из переменной EXTRA_OECONF.

4.7.5. Изменение принятого по умолчанию каталога sysroot

Принятые по умолчанию в gcc каталоги sysroot и include перенаправлены в несуществующее место, чтобы отследить использование каталогов хоста в результате отсутствия корректно переданных опций. Это применяется для кросс-компиляторов, используемых при сборке, и создаваемых в SDK. Если изменение вызывает отказ при сборке, это может означать, что флаги и команды компилятора были некорректно переданы базовым программам. В таких случаях нужно внести соответствующие правки.

4.7.6. Улучшение повторной сборки

Изменены классы base, autotools и cmake для очистки созданных файлов при необходимости повтора do_configure. Одним из улучшения является попытка выполнить команду make clean в задаче do_configure, если имеется файл Makefile. Некоторые программы не поддерживают очистки в своих файлах make. Для таких заданий нужно установить CLEANBROKEN = «1».

4.7.7. Изменения в проверках QA

Использование PRINC ранее вызывало предупреждения, а сейчас приводит к ошибке. Следует удалить использование PRINC из всех заданий и файлов добавления.
Добавлена проверка QA использования ${D} в значениях FILES там, где применять D не следует. Эта проверка гарантирует использование $D в функциях pkg_preinst, pkg_postinst, pkg_prerm, pkg_postrm вместо ${D}.
В переменной S нужно устанавливать действительное для задания значение. Если переменная S в задании не установлена, каталог автоматически не создается. Если S не указывает каталог, существующий к моменту завершения задачи do_unpack, выдается предупреждение.
Проверяется переменная LICENSE на предмет корректности форматирования множества лицензий. Если формат не пригоден (например, указано множество лицензий без оператора, определяющего их взаимодействие), выдается предупреждение.

4.7.8. Прочие изменения

Сценарий send-error-report ожидает опцию -s перед адресом сервера (это предполагает указание сервера).
Сценарий oe-pkgdata-util ожидает опции -«перед каталогом pkgdata, который сейчас можно не указывать. При отсутствии pkgdata сценарий будет запускать BitBake для запроса PKGDATA_DIR в среду сборки.

4.8. Переход на YP 2.0

В этом разделе рассмотрен переход на YP 2.0 с предыдущего выпуска.

4.8.1. GCC 5

По умолчанию используется компилятор GCC 5.2, потребовавшийся для устранения ошибок компиляции во многих заданиях. Одним из важных примеров служит ситуация, когда система «зависала» при сборке ядра Linux для ARM с компилятором GCC 5. При использовании своих заданий, собирающих ядро для ARM, вам может потребоваться внести исправление. В стандартном дереве ядра linux-yocto эти исправления уже внесены. Дополнительная информация приведена на странице https://gcc.gnu.org/gcc-5/changes.html, рекомендации по переносу — на странице https://gcc.gnu.org/gcc-5/porting_to.html.

Можно вернуться к использованию GCC версии 4.9 или 4.8 с помощью строки вида GCCVERSION = «4.9%» в файле конфигурации.

4.8.2. Удаление Gstreamer 0.10

Поддержка Gstreamer 0.10 была заменена поддержкой Gstreamer 1.x. В результате этого изменения задания для Gstreamer 0.10 и связанных программ размещены сейчас в meta-multimedia. Это ведет к тому, что в Qt4 поддержка Phonon и Gstreamer до умолчанию отключена для QtWebkit.

4.8.3. Удаленные задания

bluez4 устарело и перемещено в meta-oeв результате полной интеграции с bluez5.
gaminустарело и удалено.
gnome-icon-theme функционально заменено заданием adwaita-icon-theme.
Задания Gstreamer 0.10 удалены в пользу поддержки заданий для Gstreamer 1.x.
insserv устарело и удалено.
libunique больше не используется и перенесено в meta-oe.
midori функционально заменено заданием epiphany.
python-gst устарело и было удалено, поскольку требовалось только для Gstreamer 0.10.
qt-mobility устарело и было удалено, поскольку требует наличия Gstreamer 0.10(удалено).
subversion удалены версии 1.6.x этого задания.
webkit-gtk старая версия 1.8.3 удалена с заменой на webkitgtk.

4.8.4. Улучшение хранилища данных BitBake

Изменен метод обработки переопределений хранилищем BitBake. Переопределения сейчас применяются динамически, а bb.data.update_data() не используется. На практике это изменение вряд ли потребует какого-либо изменения метаданных. Однако имеются незначительные изменения в поведении, указанные ниже.

Все возможные переопределения теперь доступны в истории по команде bitbake -e.
d.delVar('VARNAME') и d.setVar('VARNAME', None) приводят к очистке переменной и всех ее переопределений. До изменения очищались лишь не переопределенные значения.

4.8.5. Смена поведения shell-функций

Консольные (shell) версии функций сообщений BitBake (bbdebug, bbnote, bbwarn, bbplain, bberror, bbfatal) связаны с их эквивалентами в BitBake — bb.debug(), bb.note(), bb.warn(), bb.plain(), bb.error(), bb.fatal(), соответственно. Таким образом, функции сообщений, ожидаемые в пользовательском интерфейсе BitBake UI, будут выводиться фактически. На практике это изменение имеет два проявления, описанных ниже.

Если на консоли появляются сообщения, которых ранее (до изменения) не было, может потребоваться очистка вызовов bbwarn, bberrorи т. п. Можно просто удалить эти вызовы.
Функция bbfatal подавляет полный вывод журнала ошибок в UI, поэтому при необходимости видеть этот вывод полностью нужно заменить bbfatal на die или bbfatal_log.

4.8.6. Очистка дополнительных пакетов для разработки и отладки

Удалены использованные при разработке и отладке задания для acl, apmd, aspell, attr, augeas, bzip2, cogl, curl, elfutils, gcc-target, libgcc, libtool, libxmu, opkg, pciutils, rpm, sysfsutils, tiff, xz.Для всех перечисленных заданий сейчас применяется стандартная схема, где для задания имеется один пакет-dev, -dbg, -staticdev.

4.8.7. Перенос данных отслеживания заданий в OE-Core

Поддержка данных отслеживания для заданий, которые были частью meta-yocto, перенесена на уровень OE-Core. Это относится к файлам package_regex.inc и distro_alias.inc, которые обычно включаются при использовании класса distrodata. Кроме того, содержимое файла upstream_tracking.inc теперь разделено по заданиям.

4.8.8. Автоматическая очистка устаревших файлов в sysroot

Файлы из заданий, которых уже нет в текущей конфигурации, автоматически удаляются из sysroot и других мест, управляемых общим состоянием. Эта автоматическая очистка означает, что система сборки корректно обрабатывает такие ситуации, как переименования сборочной стороны заданий, удаление уровней из bblayers.conf и изменение DISTRO_FEATURES.

В дополнение к этому очищаются каталоги старых версий заданий. Если нужно отключить такую очистку, можно установить в конфигурации переменную SSTATE_PRUNE_OBSOLETEWORKDIR = «0».

4.8.9. Репозиторий метаданных linux-yocto отделен от исходного кода

Дерево linux-yocto до этого представляло набор изменений в ядре и конфигурации (метаданных). Хотя такой формат эффективен для синхронизации конфигураций ядра и изменений в исходных кодах, разработчикам не всегда понятно, как работать с метаданными применительно к исходным кодам.

Обработка метаданные перенесена из класса kernel-yocto и применяется внешний репозиторий метаданных yocto-kernel-cache, который всегда использовался для заполнения ветви meta в linux-yocto. Отдельный репозиторий кэша linux-yocto сейчас служит основным местом хранения для этих данных. В результате linux-yocto больше не может обрабатывать комбинированные деревья. Поэтому при необходимости иметь свой комбинированный репозиторий ядра нужно будет разделить его и соответственно обновить свои задания. Примером может служить задание meta/recipes-kernel/linux/linux-yocto_4.1.bb.

4.8.10. Дополнительные проверки QA

Добавлена проверка host-user-contaminated для контроля вопросов владения файлами за пределами /home. Проверка ищет файлы, некорректно принадлежащие пользователю, запустившему BitBake, а не предусмотренному пользователю в целевой системе.
Добавлена проверка invalid-chars для обнаружения недействительных (не-UTF8) символов в значениях переменных метаданных задания (DESCRIPTION, SUMMARY, LICENSE, SECTION), поскольку некоторые менеджеры пакетов не поддерживают такие символы.
Добавлена проверка invalid-packageconfig опций PACKAGECONFIG на соответствие опциям задания.

4.8.11. Прочие изменения

gtk-update-icon-cache переименовано в gtk-icon-utils.
Элемент tools-profile в IMAGE_FEATURES, а также соответствующие packagegroup и packagegroup-core-tools-profile больше не включаются в oprofile. Внедрение в oprofile изначально было предназначено для облегчения компиляции для платформ с ограниченными ресурсами. Однако это не получило широкого распространения и вряд ли будет применяться в будущем по причине расширения возможностей платформ и усовершенствования инструментов кросс-компиляции.
Принятое по умолчанию значение переменной IMAGE_FSTYPES включает ext4 вместо ext3.
Удалена поддержка переменной PRINC.
Группа пакетов packagegroup-core-full-cmdline больше не используется в lighttpd по причине того, что это не соответствует назначению packagegroup, которое заключается в добавлении консольных инструментов, которые по умолчанию обеспечиваются busybox.

4.9. Переход на YP 2.1

В этом разделе рассмотрен переход на YP 2.1 с предыдущего выпуска.

4.9.1. Преобразование переменных в функциях Python

Выражения для переменных вида ${VARNAME} больше не преобразуются автоматически в функциях Python. Это сделано для того, чтобы позволить функциям Python создавать shell-сценарии и другой код для ситуаций, где не нужны такие преобразования. В имеющемся коде, который применяет такие преобразования, нужно изменить их для преобразования отдельных переменных с помощью d.getVar() или d.expand() для более сложных выражений.

4.9.2. Нижний регистр для переменной `OVERRIDES`

В соглашении о переопределениях всегда предполагались символы нижнего регистра. Это стало сейчас требованием, поскольку хранилище BitBake предполагает нижний регистр символов для некоторого ускорения процесса анализа. На практике это означает, что все завершающееся в OVERRIDES должно указываться символами нижнего регистра (например, значения MACHINE, TARGET_ARCH, DISTRO, а также имена заданий, если действуют переопределения _pn-recipename).

4.9.3. Параметр раскрытия функций `getVar()` и `getVarFlag()` стал обязательным

Параметр раскрытия для функций getVar() и getVarFlag() ранее по умолчанию имел значение False, однако теперь этого нет и параметр нужно задавать. Требуется заменить все вызовы getVar(), где параметр не был указан, вызовами с заданным параметром. Ниже приведен пример команды, позволяющей автоматизировать эту замену.

     sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
     sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`

Причина этого изменения заключается в том, что в будущих выпусках YP планируется по умолчанию задавать значение True. Однако изменение требуется вносить постепенно, поскольку внезапная смена может вызвать сложные в обнаружении побочные эффекты.

4.9.4. Изменение окружения Makefile

Переменная EXTRA_OEMAKE сейчас имеет по умолчанию значение «» вместо прежнего «-e MAKEFLAGS=», что было исторической случайностью, требовавшей переопределения во множестве классов (например, autotools, module) и заданий. При обновлении на этот выпуск нужно отредактировать все задания, основанные на прежнем значении, путем возврата «-e MAKEFLAGS=» или явной установки нужного значения EXTRA_OEMAKE, что обычно требуется только в случаях установки Makefile по умолчанию не подходящего для кросс-компиляции значения переменной с использованием оператора =, а не ?=.

4.9.5. Возвращение `libexecdir` к `${prefix}/libexec`

Использование ${libdir}/${BPN} в качестве libexecdir отличается от всех основных дистрибутивов, применяющих ${prefix}/libexec или ${libdir}, и противоречит стандартам кодирования GNU, задающим использование ${prefix}/libexec, а также практике задания используемой пакетом вложенности в самом пакете. Кроме того, различия libexecdir в разных заданиях осложняют этим заданиям вызов двоичных файлов, установленных в libexecdir. Стандарт FHS 7 признает использование ${prefix}/libexec/, предоставляя приложениям выбор между ${prefix}/lib и ${prefix}/libexec.

4.9.6. ac_cv_sizeof_off_t больше не кэшируется в файлах сайта

Для заданий, наследующих класс autotools, значение ac_cv_sizeof_off_t больше не кэшируется в файлах сайта для autoconf. Причина этого заключается в том, что ac_cv_sizeof_off_t не обязательно является неизменным для архитектуры, как считалось ранее, и меняется в зависимости от поддержки больших файлов. Для большинства программ, использующих autoconf, внесенное изменение не создает проблем. Однако задания, которые обходят стандартную задачу do_configure из класса autotools, и программ использующих очень старые версии autoconf, задание может не определить корректный размер off_t в процессе выполнения задачи do_configure.

Лучшим вариантом действий является исправление программ при необходимости, чтобы принятая по умолчанию реализация из класса autotools работала так, чтобы выполнялась утилита autoreconf, создающая работоспособный сценарий configure, и переопределение задачи do_configure для использования принятой по умолчанию реализации.

4.9.7. Генерация образа отделена от генерации файловой системы

Ранее задача do_rootfs для образов собирала файловую систему и помещала в нее созданные образы. С этого выпуска YP генерация образов вынесена в отдельные задачи do_image_*, чтобы отделить операции от кода.

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

Еще одна часть этого изменения заключается в переносе определений и функций пост-обработки из класса image в класс rootfs-postcommands. Функционально это ничего не меняет.

4.9.8. Удаленные задания

gcc версии 4.8 — версии 4.9 и 5.3 сохранены;
qt4 — поддержка Qt 4.x перенесена в отдельный уровень meta-qt4;
x11vnc перенесено на уровень meta-oe;
linux-yocto-3.14;
linux-yocto-3.19;
libjpeg заменено заданием libjpeg-turbo;
pth признано устаревшим;
liboil больше не нужно и перенесено на уровень meta-multimedia;
gtk-theme-torturerбольше не нужно и перенесено на уровень meta-gnome;
gnome-mime-data больше не нужно и перенесено на уровень meta-gnome;
udev заменено заданием eudev для совместимости при использовании sysvinit с новыми ядрами;
python-pygtk признано устаревшим;
adt-installer признано устаревшим (см. параграф 4.9.11. Удаление ADT).

4.9.9. Изменения классов

autotools_stage удален в результате обеспечения нужной функциональности классом autotools. Заданиям, наследовавшим autotools_stage сейчас нужно наследовать autotools.
boot-directdisk слит с классом image-vm. Класс boot-directdisk применялся редко и изменение не должно вызывать проблем.
bootimg слит с классом image-live. Класс bootimg применялся редко и изменение не должно вызывать проблем.
packageinfo удален, поскольку применялся лишь в удаленном интерфейсе Hob UI.

4.9.10. Изменения пользовательского интерфейса системы сборки

Интерфейс Hob UI на базе GTK+ удален, поскольку больше не поддерживается и основан на устаревшей библиотеке GTK+ 2. Интерфейс Toaster UI на основе web более эффективен и активно поддерживается (см. раздел Using the Toaster Web Interface [8]).
Интерфейс «puccho» BitBake UI удален, поскольку больше не поддерживается и малополезен.

4.9.11. Удаление ADT

Пакет разработки приложений ADT⁸ был удален, поскольку его функциональность практически полностью перекрывалась со стандартным SDK и расширенным SDK [7]. Плагин Yocto Project Eclipse IDE не затронут изменением.

4.9.12. Изменения в эталонном дистрибутиве Poky

Уровень meta-yocto переименован в meta-poky, что точнее отражает его назначение - эталонный дистрибутив Poky. Уровень meta-yocto-bsp сохранил свое имя, поскольку он содержит эталонные машины для YP и больше никак не связан с Poky. Ссылки на meta-yocto в файле conf/bblayers.conf должны обновиться автоматически.
Класс uninative включен в Poky по умолчанию. Этот класс пытается изолировать систему сборки от библиотеки C дистрибутива хоста и делает возможным использование естественных элементов общего состояния разными дистрибутивами хоста. При включенном класса загружается архив собранной библиотеки C в начале сборки. Класс uninative включается в файле meta/conf/distro/include/yocto-uninative.inc, что позволяет управлять им независимо от использования дистрибутива Poky.

Если нужно собрать свой архив uninative, это можно сделать с помощью задания uninative-tarball и сделать архив доступным для сборочных машин (например, по протоколу HTTP/HTTPS), а также установить похожую на yocto-uninative.inc конфигурацию.
Генерация статических библиотек сейчас по умолчанию отключена в Poky для большинства классов. Это сократило время сборки и также размер области сборки. Запрет создания таких библиотек задан в файле meta/conf/distro/include/no-static-libs.inc. В задания, которым не нужна опция —disable-static в команде configure, следует включить переменную DISABLE_STATIC = «».
В отдельном компактном дистрибутиве poky-tiny сейчас применяется библиотека musl C вместо сильно урезанной glibc. Использование musl уменьшает размер дистрибутива и упрощает поддержку. При использовании poky-tiny со своей конфигурацией glibc нужно будет изменить настройки в новом выпуске.

4.9.13. Изменения в пакетах

Двоичные файлы runuser и mountpoint из пакета util-linux перенесены в util-linux-runuser и util-linux-mountpoint.
Пакет python-elementtree объединен с пакетом python-xml.

4.9.14. Изменения в файлах настройки

Функция настройки no-thumb-interwork удалена из включаемых файлов настройки ARM, поскольку для ARM EABI требуется взаимодействие, эта функция не имеет смысла.
Отменена поддержка ARM OABI в gcc 4.7.
Удалены файлы tune-cortexm*.inc и tune-cortexr4.inc, поскольку они не были достаточно протестированы. Пока система сборки OE не будет официально поддерживать CPU без MMU, эти файлы лучше держать на отдельном уровне, если они нужны.

4.9.15. Поддержка GObject Introspection

Этот выпуск поддерживает генерацию файлов GIR⁹ с помощью самоанализа GObject, который является стандартным механизмом доступа к программам на основе GObject. Можно включать, отключать и тестировать генерацию таких данных, как описано в разделе Enabling GObject Introspection Support [2].

4.9.16. Прочие изменения

Минимальная версия Git заменена на 1.8.3.1. Если сборочных хост имеет более старую версию, следует установить нужные пакеты, как указано в параграфе 1.3. Требуемые версии Git, tar и Python.
Ошибочная и неполная поддержка менеджера пакетов RPM версии 4 была удалена. Проверенная и поддерживаемая версия 5 для RPM сохранена.
Ранее было указано, что удаляются пакеты update-rc.d, base-passwd, shadow, update-alternatives, run-postinsts, если package-management нет в IMAGE_FEATURES. В выпуске YP 2.1 эти пакеты удаляются лишь при наличии read-only-rootfs в IMAGE_FEATURES, поскольку они могут требоваться для образов с доступом на чтение и запись даже при отсутствии менеджера пакетов (например, для добавления, изменения или удаления пользователей в процессе работы).
Команда devtool modify по умолчанию извлекает исходный код в соответствии с ожиданиями. Опции -x и —extract больше не работают. Если нужно указать свое дерево исходных кодов, следует задать опцию -n или —no-extract для команды devtool modify.
Если форм-фактор для машины не указан или не говорит о наличии клавиатуры, это наличие предполагается по умолчанию. Основное влияние это изменение оказывает на Sato UI.
Каталоги упаковки .debug создаются автоматически. Если задание собирает пакеты, которые устанавливают двоичные файлы в нестандартные каталоги, больше не нужно заботиться об установке FILES_${PN}-dbg для указания каталогов .debug.
Неточные данные о процентах занятости диска и CPU удалены из вывода buildstats с заменой данными getrusage() и корректной статистикой ввода-вывода. Возможно потребуется обновление пользовательского кода для чтения данных buildstats.
Файл meta/conf/distro/include/package_regex.inc отменен с переносом содержимого в отдельные задания. Поскольку этот файл скорей всего будет удален в новых выпусках YP, предлагается убрать все ссылки на него из вашей конфигурации.
Файл v86d/uvesafb удален из эталонных машин genericx86 и genericx86-64 уровня meta-yocto-bsp. Большинство современных плат x86 не использует этот файл и он лишь добавляет сообщения об ошибках ядра при запуске. Если поддержка uvesafb нужна, можно добавить v86d в образ.
Пути сборки sysroot удалены из файлов с отладочными символами. Это означает, что удаленный отладчик GDB, использующий невырезанные символы сборки sysroot, больше не сможет работать (хотя такая работа никогда и не документировалась). Поддерживаемым методом для выполнения похожих операций является установка IMAGE_GEN_DEBUGFS = «1», при которой будет создаваться сопровождающий отладочный образ вместе с данными для отладки.

4.10. Переход на YP 2.2

В этом разделе рассмотрен переход на YP 2.2 с предыдущего выпуска.

4.10.1. Минимальная версия ядра

Минимальная версия ядра для целевых платформ и SDK сейчас 3.2.0 в результате перехода на glibc 2.24. Для платформ AArch64 нужна версия 3.14, для Nios II — 3.19. Для систем x86 и x86_64 при необходимости можно сбросить OLDEST_KERNEL до версии 2.6.32.

4.10.2. Упрощено упорядочение каталогов в sysroot

Упорядочение каталогов в sysroot упрощено и добавлены переменные SYSROOT_DIRS, SYSROOT_DIRS_NATIVE и SYSROOT_DIRS_BLACKLIST. Дополнительная информация приведена в списке рассылки OE-Core ( v2 patch series).

4.10.3. Включено удаление старых образов и других файлов из `tmp/deploy`

Удаление старых образов и других файлов из tmp/deploy/ включено по умолчанию в результате использования для этих файлов нового метода подготовки. В результате переменная RM_OLD_IMAGE стала избыточной.

4.10.4. Изменения Python

4.10.4.1. BitBake требует Python 3.4+

BitBake требует Python версии 3.4 или выше.

4.10.4.2. На сборочном хосте требуется UTF-8 Locale

Python 3 требует на сборочном хосте установки UTF-8. Поскольку C.UTF-8 не является стандартом, по умолчанию применяется en_US.UTF-8.

4.10.4.3. Метаданные должны использовать синтаксис Python 3

Для метаданных теперь требуется синтаксис Python 3. Рекомендации по подготовке метаданных можно найти в любом из руководств по переносу в Python 3. Можно также согласиться на фиксации (commit) преобразования для Bitbake и использовать OE-Core в качестве руководства. Ниже перечислены наиболее важные области.

Конвейеры командной строки субпроцессов требуют декодирования locale.
Изменен синтаксис восьмеричных значений.
Изменены имена функции iter*().
Итерации возвращают представления (view), а не списки.
Изменены имена модулей Python.

4.10.4.4. Задания Python для целевых платформ переключены на Python 3

Большинство заданий Python для целевых платформ переведены на Python 3. К сожалению, системы с менеджером пакетов RPM и его поддержкой через SMART продолжают использовать Python 2.

Python 2 и применяющие его задания могут пока собираться для целевых платформ как в прежних версиях.

4.10.4.5. Архив `buildtools` включает Python 3

Архив buildtools сейчас включает Python 3.

4.10.5. Замена uClibc на musl

Библиотека uClibc была заменена библиотекой musl, которая лучше разработана, широко поддерживается и совместима с большим числом приложений, нежели uClibc.

4.10.6. `${B}` больше не служит для задач рабочим каталогом по умолчанию

${B} больше не является принятым по умолчанию рабочим каталогом для задач. Поэтому все пользовательские задачи должны иметь флаг [dirs] или в задачах рабочий каталог должен быть указан вручную (например, командой cd). Предпочтительно использовать флаг [dirs].

4.10.7. Сценарий `runqemu` переписан на Python

Сценарий runqemu был переписан на Python и поведение в некоторых случаях изменилось. Прежние шаблоны поведения поддерживаются.

В новом сценарии runqemu на Python информация о машине уже не задана жестко и можно выбрать использование конфигурационного файла qemuboot,чтобы определить собственные аргументы BSP и сделать его загружаемым с помощью runqemu. Конфигурационный файл имеет форму image-name—machine.qemuboot.conf.

Файл конфигурации включает тонкую настройку опций, передаваемых QEMU без жесткого кодирования сценария runqemu и информации о разных машинах. Использование конфигурационного файла удобно, в частности, при попытке использования QEMU с машинами, отличающимися от qemu* в OE-Core. Файл qemuboot.conf создается классом qemuboot при сборке корневой файловой системы (rootfs). Аргументы загрузки QEMU могут быть заданы в конфигурационном файле BSP и класс qemuboot сохранит их в qemuboot.conf.

При использовании runqemu без файла конфигурации применяется команда вида

$ runqemu machine rootfs kernel [options]

Поддерживаются машины qemuarm, qemuarm64, qemux86, qemux86-64, qemuppc, qemumips, qemumips64, qemumipsel, qemumips64el.

Рассмотрим пример использования машины qemux86-64, обеспечивающий корневую файловую систему, образ и использование опции nographic.

$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic

Ниже приведен список переменных, которые могут быть установлены в конфигурационном файле (например, bsp.conf) для загрузкиBSP с помощью runqemu.

"QB" means "QEMU Boot". 
QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
QB_MEM: Memory (e.g. "-m 512")
QB_MACHINE: QEMU machine (e.g. "-machine virt")
QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
		option (e.g. "console=ttyS0 console=tty")
QB_DTB: QEMU dtb name
QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
		when QB_AUDIO_DRV is set.
QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
QB_TAP_OPT: Network option for 'tap' mode (e.g. "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no 
		-device virtio-net-device,netdev=net0").
		runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
QB_ROOTFS_OPT: Used as rootfs (e.g.
		"-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
		runqemu will replace "@ROOTFS@" with the one which is used, such as
		core-image-minimal-qemuarm64.ext4.
QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
QB_TCPSERIAL_OPT: tcp serial port option (e.g.
		" -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -
		device      virtconsole,chardev=virtcon"
		runqemu will replace "@PORT@" with the port number which is used.

Для использования runqemu, устанавливается переменная IMAGE_CLASSES += «qemuboot» и запускается runqemu.

Синтаксис командной строки можно узнать с помощью команды runqemu help.

4.10.8. Изменен стиль хеширования принятого по умолчанию компоновщика

Компоновщик теперь по умолчанию применяет для кросс-компиляции gcc стиль хэширования sysv, чтобы перехватывать задания, создающие программы без использования LDFLAGS. Это изменение может создавать некоторые QA при сборке таких заданий в виде сообщений No GNU_HASH10. Для решения проблемы нужно изменить эти задания, чтобы они применяли LDFLAGS. В зависимости от способа сборки (например, Makefile) может потребоваться исправление системы сборки. Иногда достаточно добавить TARGET_CC_ARCH += «${LDFLAGS}».

4.10.9. `KERNEL_IMAGE_BASE_NAME` больше не использует `KERNEL_IMAGETYPE`

Переменная KERNEL_IMAGE_BASE_NAME больше не использует KERNEL_IMAGETYPE для создания базового имени образа. Поскольку система сборки OE может создавать множество типов образов ядра, эта часть базового имени была удалена, а сохранено лишь KERNEL_IMAGE_BASE_NAME ?= «${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}. При наличии заданий или классов, использующих KERNEL_IMAGE_BASE_NAME напрямую, может потребоваться обновление ссылок.

4.10.10. BitBake

Инструменты goggle UI и автономный image-writer удалены, поскольку им нужна поддержка GTK+ 2.0.
Сборщик Perforce сейчас поддерживает SRCREV для указания используемого выпуска исходного кода (${AUTOREV}, номер списка изменений, p4date или метка) вместо отдельных параметров SRC_URI. Это изменение больше соответствует другим сборщикам, работающим с системами контроля версий. Задания, использующие Perforce, следует обновить для работы с SRCREV вместо SRC_URI.
Нужно изменить некоторые внутренние структуры кода BitBake для доступа к кэшу заданий с целью поддержки новой функциональности с множеством конфигураций. Эти изменения будут влиять на внешние инструменты, применяемые в BitBake модулем tinfoil. Информация об этих изменениях доступна в описаниях изменений сценариев из состава OpenEmbedded-Core (1 и 2).
Переписан код управления задачами для предотвращения использования косвенных идентификаторов, что позволило повысить производительность. Это изменение не должно вызывать проблем для большинства пользователей. Однако для проверки подписей нужна функция setscene, указываемая переменной BB_SETSCENE_VERIFY_FUNCTION. Поэтому добавлена переменная BB_SETSCENE_VERIFY_FUNCTION2, разрешающая нескольким версиям BitBake работать с подходящими метаданными, включая OpenEmbedded-Core и Poky. При использовании своих планировщиков задач BitBake может потребоваться обновление кода для работы с новой структурой.

4.10.11. Удален инструмент Swabber

Инструмент Swabber, предназначенный для обнаружения «мусора» в процессе сборки, был удален, поскольку некоторое время не поддерживается и никогда не был достаточно эффективным. Система сборки OE включает ряд механизмов (в том числе проверки QA), позволяющих обойтись без этого инструмента.

4.10.12. Удаленные задания

augeas больше не требуется и перенесено в meta-oe.
directfb не поддерживается и перенесено в meta-oe.
gcc — удалена версия 4.9 с сохранением версий 5.4 и 6.2.
gnome-doc-utils больше не требуется.
gtk-doc-stub заменено gtk-doc.
gtk-engines больше не требуется и перенесено в meta-gnome.
gtk-sato-engine устарело.
libglade больше не требуется и перенесено в meta-oe.
libmad не поддерживается и функционально заменено libmpg123 с переносом libmad в meta-oe.
libowl устарело.
libxsettings-client больше не требуется.
oh-puzzles функционально заменено puzzles.
oprofileui устарело. OProfile в значительной степени вытеснен perf.
packagegroup-core-directfb.bb.
core-image-directfb.bb.
pointercal больше не требуется и перенесено в meta-oe.
python-imaging больше не требуется и перенесено в meta-python
python-pyrex больше не требуется и перенесено в meta-python.
sato-icon-theme устарело.
swabber-native — утилита удалена Swabber (параграф 4.10.11. Удален инструмент Swabber).
tslib больше не требуется и перенесено в meta-oe.
uclibc удалено с заменой на musl.
xtscal больше не требуется и перенесено в meta-oe.

4.10.13. Удаленные классы

distutils-native-base больше не требуется.
distutils3-native-base больше не требуется.
sdl устанавливает лишь переменные DEPENDS и SECTION, которые лучше назначать в задании.
sip практически не применялся.
swabber (см. параграф 4.10.11. Удален инструмент Swabber).

4.10.14. Второстепенные изменения в пакетах

grub — grub-editenv перенесен в отдельный пакет.
systemd — связанные с container и vm блоки выделены в новый пакет systemd-container.
util-linux — prlimit выделен в пакет util-linux-prlimit.

4.10.15. Прочие изменения

Файлpackage_regex.inc удален в результате переноса определений в соответствующие задания.
Команды devtool add и recipetool create используют по умолчанию фиксированное значение SRCREV при сборке из репозиториев Git. Значение можно переопределить с помощью опции -a или ‐‐autorev для использования во всех случаях ${AUTOREV}.
distcc интерфейс GTK+ UI по умолчанию отключен.
packagegroup-core-tools-testapps — удалено Piglit.
image.bbclass — COMPRESS(ION) переименована в CONVERSION. Это означает замену COMPRESSIONTYPES, COMPRESS_DEPENDS и COMPRESS_CMD на CONVERSIONTYPES, CONVERSION_DEPENDS и CONVERSION_CMD. Имена переменных COMPRESS* будут работать в выпуске 2.2, но метаданные, которым не нужна совместимость с прежними версиями, следует переименовать, поскольку COMPRESS* в будущих выпусках не планируется поддерживать.
gtk-doc — доступна полная версия. Однако некоторые старые программы могут оказаться не способными применять новую версию для создания документации. Нужно изменить задания, собирающие такие программы, для явного запрета создания документации с помощью gtk-doc.

4.11. Переход на YP 2.3

В этом разделе рассмотрен переход на YP 2.3 с предыдущего выпуска.

4.11.1. Sysroot для задания

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

Объявление зависимостей при сборке. Поскольку это новая возможность, нужно явно объявить все зависимости при сборке задания. Если зависимости не указать, они не будут включены в sysroot для задания.
Указание зависимостей естественных инструментов предустановки и пост-установки. Нужно конкретно указать все зависимости от естественных инструментов для сценариев pkg_preinst и pkg_postinst с помощью переменной PACKAGE_WRITE_DEPS. Это обеспечит доступность инструментов при необходимости запуска сценариев на хосте сборки при выполнении задачи do_rootfs.

Рассмотрим, например, задание dbus,которое имеет сценарийpkg_postinst,вызывающийsystemctl,если systemd имеется в переменной DISTRO_FEATURES. В этом случае systemd-systemctl-native добавляется в переменную PACKAGE_WRITE_DEPSс учетом наличияsystemd в переменной DISTRO_FEATURES.
Проверка заданий, использующих SSTATEPOSTINSTFUNCS. Функции, добавленные в SSTATEPOSTINSTFUNCS,вызываются как в прежних выпускахYP. Однако в результате того, что sysroot сейчас заполняется отдельно для каждого задания при наличии перемещений в функциях, вызываемых через SSTATEPOSTINSTFUNCS нужно будет внести изменения для использования сценария пост-установки, установленного функцией, добавленной в SYSROOT_PREPROCESS_FUNCS. Примером может служить класс pixbufcache в каталоге meta/classes/ Yocto Project Source Repositories.

Сама переменная SSTATEPOSTINSTFUNCS сейчас отменена с заменой на задачу do_populate_sysroot[postfuncs]. Поэтому при наличии функций, которые нужно вызывать после создания sysroot для задания, разумно будет предпринять шаги для использования сценария пост-установки, как описано выше. Это подготовит код к удалению SSTATEPOSTINSTFUNCS в будущем выпуске YP.
Указание sysroot при использовании некоторых внешних сценариев. Поскольку общий каталог sysroot сейчас отсутствует, сценарии oe-find-native-sysroot и oe-run-native были изменены так, что требуется указать какое задание используется в STAGING_DIR_NATIVE.

Дополнительная информация о работе sysroot для заданий приведена в параграфе 6.127. staging.bbclass.

4.11.2. Переменная `PATH`

В среде, используемой для работы задач сборки, переменная PATH теперь очищается с удалением естественных путей (/bin, /sbin, /usr/bin и т. п.) и символьные ссылки указывают только на двоичные файлы сборочного хоста, указанные в переменных HOSTTOOLS и HOSTTOOLS_NONFATAL,добавленных вPATH. Поэтому все естественные двоичные файлы, предоставляемые хостом, должны включаться в эти две переменные на уровне настройки.

Другим вариантом является добавление задания -nativeв переменнуюDEPENDS. Переменная PATH в этом случае не очищается в devshellтаким же способом, поскольку это создало бы проблемы при запуске инструментов хоста в среде разработки.

4.11.3. Изменение сценариев

oe-find-native-sysroot — применение сценария изменилось и имеет форму
```
$ . oe-find-native-sysroot recipe
```
Сейчас задание должно указываться как часть команды, что до версии YP 2.7.1 не требовалось.
oe-run-native — применение сценария изменилось и имеет форму
```
$ oe-run-native native_recipe tool
```
Сейчас естественное задание должно указываться как часть команды, что до версии YP 2.7.1 не требовалось.
cleanup-workdir — удален в результате обнаружения наносимых им повреждений дерева сборки (удаление файлов). Вместо удаления части TMPDIR рекомендуется удалять TMPDIR полностью и восстанавливать из общего состояние (sstate) при последующей сборки.
wipe-sysroot удален, поскольку больше не требуется.

4.11.4. Изменения функций

Ранее отмененные функции bb.data.getVar(), bb.data.setVar()удалены с заменой наd.getVar(), d.setVar()и т. п. Следует исправить ссылки на старые функции.

4.11.5. BitBake

Заменен интерфейс depexp. Графический интерфейс исследования зависимостей BitBake depexp заменен интерфейсом taskexp (Task Explorer), обеспечивающим графическое представление файла task-depends.dot. Представляемые этим интерфейсом данные более точны, нежели данные depexp. Визуализация данных является часто запрашиваемой функцией, поскольку стандартные средства просмотра файлов *.dot зачастую не справляются с размером task-depends.dot.
Изменен вывод bitbake -g. Файлы package-depends.dot и pn-depends.dot,которые раньше создавались командойbitbake -g,удалены. Сейчас генерируется файл recipe-depends.dot,являющийся сокращенным вариантомtask-depends.dot. Это изменение вызвано тем, что файлы package-depends.dot и pn-depends.dotв значительной степени относятся ко времени до выполнения на основе задач и не учитывают зависимостей между заданиями, что может вводить в заблуждение.
Изменение переменных для зеркал. Переменные для зеркал, включая MIRRORS, PREMIRRORS и SSTATE_MIRRORS позволяют теперь разделять значения пробелами, поэтому больше не нужно использовать \\n. BitBake ищет пары значений, что упрощает использование. Для имеющихся переменных не должно требоваться каких-либо изменений.
Сборщик SVN использует параметр ssh, а не rsh. Этот новый необязательный параметр используется при установке protocol = svn+ssh. Параметр может применяться лишь для указания программы ssh, используемой SVN. Сборщик SVN передает параметр через переменную SVN_SSH при выполнении задачи do_fetch. Дополнительная информация приведена в разделе Subversion (SVN) Fetcher (svn://).
Удалены BB_SETSCENE_VERIFY_FUNCTION и BB_SETSCENE_VERIFY_FUNCTION2, поскольку применявший их механизм больше не используется для связанных с заданиями систем sysroot.

4.11.6. Абсолютные символьные ссылки

Абсолютные символьные ссылки (symlink) больше не разрешены в промежуточных (stage) файлах и вызывают ошибку. Для явного создания символьных ссылок может использоваться сценарий lnr, который заменяет команду ln -r. Если сценарий сборки в создаваемой заданием программе создает абсолютные символьные ссылки, которые нужно исправлять, можно наследовать в задании класс relative_symlinks для преобразования ссылок в относительные.

4.11.7. Версии GPLv2 для заданий GPLv3 перенесены

Старые GPLv2-версии заданий GPLv3 перенесены на отдельный уровень meta-gplv2. При использовании INCOMPATIBLE_LICENSE для исключения GPLv3 или PREFERRED_VERSION для подстановки GPLv2-версий заданий GPLv3 нужно добавить в конфигурацию уровень meta-gplv2, доступный
по ссылке.

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

Долгосрочным решением может быть переход на компоненты с лицензией BSD, заменяющие компоненты GPLv3, если требуется исключить лицензии GPLv3 из системы. Это решение будет исследовано в новых выпусках YP.

4.11.8. Изменение управления пакетами

Менеджер пакетов Smart был заменен на DNF. Smart больше не разрабатывается и не перенесен на Python 3.x. Единственным кандидатом на замену оказался пакет DNF.

Изменение функциональности заключается в том, что управление пакетами на целевой платформе во время работы с удаленного хранилища пакетов выполняется другим инструментом с иным набором команд. При наличии сценариев, вызывавших инструмент напрямую или через API, их нужно изменить. Информация о менеджере DNF доступна по ссылке.
Rpm 5.x заменен на Rpm 4.x по двум основным причинам:

- DNF не совместим на уровне API с 5.x, а перенос и поддержка являются сложными задачами;
- Rpm 5.x имеет ограниченную поддержку и YP является одним из немногих применений.

Поддержка Berkeley DB 6.x удалена и по умолчанию используется Berkeley DB 5.x.

- Версия 6.x Berkeley DB была отвергнута значительной частью сообщества по причине лицензии AGPLv3. В результате большинство проектов с открытым кодом, использующих DB, продолжает работать с DB 5.x.
- В OE-core использование DB 6.x нужно было лишь Rpm 5.x и нет причин сохранять DB 6.x в OE-core.

Инструментcreaterepo заменен createrepo_c, который является современным средством генерации метаданных удаленного репозитория и работает быстрее, чем createrepo(язык c вместоPython).
Независимые от архитектуры пакеты RPM теперь используют суффикс noarch вместо all.

Это обусловлено тем, во многих случаях использования DNF/RPM4 такой переход уже произошел. Меняются лишь имена файлов и теги архитектуры. Никаких иных изменений не вносится в OE-core и класс allarch.bbclass.
Подписание удаленных хранилищ пакетов с помощью PACKAGE_FEED_SIGN не поддерживается. Проблема будет полностью решена в новом выпуске YP (см. defect 11209 ).
OPKG сейчас использует по умолчанию библиотеку libsolv для учета зависимостей пакетов, что значительно превосходит использовавшийся ранее внутренний инструмент OPKG. Изменение ведет к незначительному росту размера на диске (около 500 кбайт) и расхода оперативной памяти (см. commit message).

4.11.9. Удаленные задания

linux-yocto 4.8 — версия 4.8 удалена, версии 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) и 4.10 сохранены.
python-smartpm — функционально заменено dnf.
createrepo — заменено createrepo-c.
rpmresolve — больше не требуется в результате перехода на RPM 4 по причине использования самого RPM.
gstreamer — удалены задания GStreamer Git, поскольку они устарели. Задания 1.10.x сохранены.
alsa-conf-base — объединено с alsa-conf, поскольку libasound зависит от обоих.
tremor — перенесено в meta-multimedia. Целочисленное декодирование Vorbis не требуется современному оборудованию. Поэтому подключаемый модуль GStreamer ivorbis по умолчанию отключен, что избавляет от необходимости включать задание tremor в OE-Core.
gummiboot — заменено systemd-boot.

4.11.10. Изменения Wic

Используемый по умолчанию выходной каталог. Сейчас Wic использует текущий каталог, а не /var/tmp/wic. Опции -o и —outdir сохранились и служат для задания предпочтительного выходного каталога.
Удален подключаемый модуль fsimage. Плагин Wic fsimage дублировал функциональность rawcopy.

Описание Wic доступно в разделе Creating Partitioned Images Using Wic [2].

4.11.11. Изменения QA

Проверкаunsafe-references-in-binaries, отключенная по умолчанию, была удалена. Эта проверка была предназначена для обнаружения двоичных файлов в каталоге /bin,связанных с библиотеками в/usr/lib для случая наличия у пользователя каталога /usr на отдельной от /файловой системе.

Удаленная проверка имела ошибки. Каталог /usr сейчас редко размещается в разделе отдельном от /.
Проверкаfile-rdeps сейчас по умолчанию возвращает ошибку, а не предупреждение. Поэтому требуется решить проблемы с невыполненными зависимостями. Дополнительная информация приведена в параграфах 6.56. insane.bbclass и 10.2. Ошибки и предупреждения.

4.11.12. Прочие изменения

В этом выпуске изменено множество заданий для игнорирования элемента largefile в DISTRO_FEATURES, включающего безусловную поддержку больших файлов. Свойство всегда было включено по умолчанию, а его отключение не тестировалось достаточно широко. В будущих выпусках YP возможность отключения свойства поддержки больших файлов будет упразднена совсем.
Если значение DISTRO_VERSION включает значение переменной DATE, которое принято по умолчанию для выпусков Poky, значение DATE явно исключается из /etc/issue и /etc/issue.net, которые выводятся в приглашении на регистрацию в системе, чтобы избежать конфликтов при использовании нескольких библиотек (Multilib). В любом случае значение DATE не является точным, если задание base-files восстановлено из общего состояния (sstate), а не собрано заново.

Если нужно записать дату сборки в /etc/issue* или иное место образа, лучше всего задать для этого функцию пост-обработки и вызвать ее из команды ROOTFS_POSTPROCESS_COMMAND. Это обеспечит соответствие значения моменту создания образа.
Сценарий инициализации Dropbear сейчас по умолчанию запрещает DSA-ключи хоста. Это изменение соответствует файлу службы systemd, который поддерживает только ключи RSA, и свежим версиям OpenSSH, где не поддерживаются ключи DSA для хоста.
Класс buildhistory сейчас корректно использует символы табуляции в качестве разделителей колонок в файле installed-package-sizes.txt,что позволяет импортировать этот файл.
Переменная USE_LDCONFIG заменена свойствомldconfig в переменной DISTRO_FEATURES. Дистрибутивам, которые раньше задавали USE_LDCONFIG = «0», следует вместо этого указывать DISTRO_FEATURES_BACKFILL_CONSIDERED_append = » ldconfig».
Принятое по умолчанию значение COPYLEFT_LICENSE_INCLUDE сейчас включает все версии лицензий AGPL в дополнение к GPL и LGPL. Заданный по умолчанию список не гарантирует полноты и следует обратиться к юридическим документам с учетом дистрибутива, если нет полной уверенности.
Пакеты модулей ядра сейчас имеют суффиксы с номером версии для возможности сосуществования на целевой системе нескольких версий ядра. Для возврата к прежней схеме именования без суффиксов следует указать KERNEL_MODULE_PACKAGE_SUFFIX = «».
Удаление файлов libtool *.la сейчас включено по умолчанию, поскольку эти файлы реально не нужны в Linux и их перемещение создает дополнительную нагрузку. Если нужно сохранить такие файлы, следует изменить переменную INHERIT_DISTRO,чтобы она не включала значение «remove-libtool».
Расширяемые SDK, собранные для GCC 5+, сейчас отвергают установку в дистрибутивы с версиями GCC на хосте 4.8 или 4.9. Это изменение вызвано тем, что известно об отказе при инсталляции из-за способа сборки общего состояния uninative (sstate). Дополнительные сведения приведены в параграфе 6.140. uninative.bbclass.
Все естественные и nativesdk задания теперь используют раздельные значения DISTRO_FEATURES вместо общего для заданий платформы, чтобы избежать неоправданной повторной сборки. В качестве DISTRO_FEATURES для естественных заданий служит DISTRO_FEATURES_NATIVE,добавленная к пересечению переменныхDISTRO_FEATURES и DISTRO_FEATURES_FILTER_NATIVE. Для заданий nativesdk соответствующими переменными являются DISTRO_FEATURES_NATIVESDK и DISTRO_FEATURES_FILTER_NATIVESDK.
Переменная FILESDIR, которая ранее была отменена и применялась редко, сейчас удалена совсем. Следует заменить в заданиях эту переменную на FILESPATH.
Переменная MULTIMACH_HOST_SYS удалена, поскольку уже не нужна для связанных с заданиями sysroot.

4.12. Переход на YP 2.4

В этом разделе рассмотрен переход на YP 2.4 с предыдущего выпуска.

4.12.1. Режим присутствия в памяти

Постоянный режим теперь доступен в принятой по умолчанию работе BitBake вместо прежнего резидентного режима (memory resident mode, т. е. oe-init-build-env-memres). Сейчас нужно лишь установить тайм-аут в переменной BB_SERVER_TIMEOUT (секунды) и сервер BitBake будет оставаться в памяти заданное время между вызовами. Сценарий oe-init-build-env-memres удален за ненадобностью.

4.12.2. Изменения в пакетах

python3

- Основной пакет python3 теперь содержит весь стандартный дистрибутив Python 3. Это соответствует поведению, ожидаемому в традиционных дистрибутивах Linux. Если нужно установить лишь часть Python 3, указывается python-core и один или несколько отдельных пакетов, которые нужны.
- python3 — сценарии bz2.py, lzma.py, и _compression.py перенесены из python3-misc в python3-compression.

binutils — библиотека libbfd помещена в отдельный пакет libbfd, что экономит пространство при установке некоторых инструментов (например, perf), когда нужна лишь библиотека libbfd а не весь пакет binutils.
util-linux

- Программа su помещена в отдельный пакет util-linux-su, который собирается только при наличии pam в переменной DISTRO_FEATURES. Пакет util-linux should не следует устанавливать, пока он не требуется, поскольку su обычно предоставляется через файл shadow. Основной пакет util-linux зависит при работе (RDEPENDS) от util-linux-su, если pam присутствует в DISTRO_FEATURES.
- Программа switch_root program помещена в отдельный пакет util-linux-switch-root для небольших образов initramfs, которым не нужен весь пакет util-linux или исполняемый файл busybox, которые значительно больше switch_root. В основном пакете util-linux имеется рекомендуемая зависимость (RRECOMMENDS) от пакета util-linux-switch-root.
- Программа ionice помещена в отдельный пакет util-linux-ionice. В основном пакете util-linux имеется рекомендуемая зависимость (RRECOMMENDS) от пакета util-linux-ionice.

initscripts - программа sushell помещена в отдельный пакет initscripts-sushell, что позволяет системам получать sushell при включенном selinux. Это избавляет от необходимости устанавливать весь пакет initscripts. Основной пакет initscripts зависит при работе (RDEPENDS) от sushell, если selinux присутствует в DISTRO_FEATURES.
glib-2.0 сейчас имеет рекомендованную зависимость (RRECOMMENDS) от пакета shared-mime-info, поскольку значительная часть GIO бесполезна при отсутствии базы данных MIME. Можно исключить зависимость через переменную BAD_RECOMMENDATIONS, если пакет shared-mime-info слишком велик и не требуется.
Стандартный запуск Go. Стандартная среда запуска Go выделена из основного задания go в go-runtime.

4.12.3. Удаленные задания

acpitests не поддерживается.
autogen-native больше не требуется для Grub, oe-core, meta-oe.
bdwgc уже не требуется в OpenEmbedded-Core и перенесено в meta-oe.
byacc нужно лишь для rpm 5.x и перенесено в meta-oe.
gcc (5.4) — версия 5.4 не поддерживается с заменой на 6.3/7.2.
gnome-common не поддерживается и больше не требуется.
go-bootstrap-native — Go 1.9 выполняет загрузку самостоятельно, поэтому задание удалено.
guile требовалось только в autogen-native и remake, а теперь не нужно этим программам.
libclass-isa-perl ранее требовалось для LSB 4, а сейчас не нужно.
libdumpvalue-perl ранее требовалось для LSB 4, а сейчас не нужно.
libenv-perl ранее требовалось для LSB 4, а сейчас не нужно.
libfile-checktree-perl ранее требовалось для LSB 4, а сейчас не нужно.
libi18n-collate-perl ранее требовалось для LSB 4, а сейчас не нужно.
libiconv требовалось только для uclibc, удаленной в предыдущем выпуске. Библиотеки glibc и musl имеют свои реализации, meta-mingw требуется для libiconv, поэтому перенесено в meta-mingw.
libpng12 ранее требовалось для LSB. Сейчас применяется libpng 1.6.x.
libpod-plainer-perl ранее требовалось для LSB 4, а сейчас не нужно.
linux-yocto (4.1) удалено с заменой на 4.4, 4.9, 4.10, 4.12.
mailx ранее требовалось для совместимости с LSB, разработка прекращена.
mesa (только версия git) — git-версия задания устарела по сравнению с версией выпуска.
ofono (только версия git) — git-версия задания устарела по сравнению с версией выпуска.
portmap устарело и заменено rpcbind.
python3-pygpgme устарело и не поддерживается. Ранее требовалось для пакета dnf, который переключен сейчас на gpgme Python.
python-async удалено с переносом на Python 3.
python-gitdb удалено с переносом на Python 3.
python-git удалено с переносом на Python 3.
python-mako удалено с переносом на Python 3.
python-pexpect удалено с переносом на Python 3.
python-ptyprocess удалено с переносом на Python 3.
python-pycurl не применяется в OpenEmbedded-Core (meta-oe).
python-six удалено с переносом на Python 3.
python-smmap удалено с переносом на Python 3.
remake в качестве провайдера virtual/make больше не применяется, поэтому не нужно в OpenEmbedded-Core.

4.12.4. Перенос дерева устройств ядра

Поддержку дерева устройств ядра сейчас проще включить в задании для ядра, поскольку код дерева устройств перенесен в класс kernel-devicetree. Функциональность включается автоматически для любого задания, наследующего класс kernel и установившего переменную KERNEL_DEVICETREE. Прежний механизм с файлом meta/recipes-kernel/linux/linux-dtb.incпродолжает работать, но вызывает предупреждения. В будущих выпусках YP файл meta/recipes-kernel/linux/linux-dtb.incпредполагается удалить. Рекомендуется исключить все обязательные операторы, запрашивающие meta/recipes-kernel/linux/linux-dtb.inc, из заданий для ядер.

4.12.5. Изменения QA для пакетов

Проверка unsafe-references-in-scripts удалена.
При указании ${COREBASE}/LICENSE в LIC_FILES_CHKSUM выдается предупреждение, поскольку файл является описанием лицензии для OE-Core. Следует применять ${COMMON_LICENSE_DIR}/MIT,если задание использует лицензиюMIT и нет возможности задать предпочтительный метод указания файла в дереве кода.

4.12.6. Изменения в файлах `README`

Основной файл Poky README перенесен на уровень meta-poky и переименован в README.poky. Для прежнего местоположения создана символьная ссылка.
Файл README.hardware перенесен на уровень meta-yocto-bsp с символьной ссылкой на прежнее место.
Создан файл README.qemu для машин qemu*.

4.12.7. Прочие изменения

Удалена переменная ROOTFS_PKGMANAGE_BOOTSTRAP и все ссылки на нее, поэтому следует исключить переменную из своих заданий.
Удален каталог meta-yocto. В выпуске YP 2.1 уровень meta-yocto был переименован в meta-poky, а подкаталог meta-yocto сохранили для предотвращения проблем в имеющихся конфигурациях.
Файл maintainers.inc, который указывал сопровождающих путем указания ответственного за каждое задание в OE-Core, перенесен из meta-poky в OE-Core (из meta-poky/conf/distro/include в meta/conf/distro/include).
Класс buildhistory делает одну фиксацию (commit) на сборку, а не на подкаталог репозитория. Это предполагает, что фиксация разрешена (BUILDHISTORY_COMMIT = «1»), что является обычным делом. Ранее класс buildhistory делал фиксацию на подкаталог репозитория для упрощения просмотра изменений в каталоге. Сейчас для просмотра таких изменений следует указывать каталог в качестве последнего параметра команды git show или git diff.
Файл x86-base.inc, включаемый во все конфигурации машин x86, устанавливает IMAGE_FSTYPES ?= «live», вместо использования оператора +=. Это упрощает переопределение принятого по умолчанию значения.
BitBake выдает множество событий BuildStarted при включенном множестве конфигураций (одно событие на конфигурацию). Дополнительная информация приведена в разделе Events [4].
По умолчанию файл security_flags.inc устанавливает переменную GCCPIE с опцией включения PIE11 в gcc, что осложняет организацию атак ROP¹².
OE-Core предоставляет подключаемый модуль bitbake-layers с командой create-layer, реализация которой привела к ненужности сценария yocto-layer, который
может быть удален из будущих выпусков YP.
Типы vmdk, vdi, qcow2 для файлов образов сейчас применяются вместе с типом образа wic через переменную CONVERSION_CMD. Эквивалентные типы образов имеют значения wic.vmdk, wic.vdi и wic.qcow2.
do_image_<type>[depends] было заменено переменной IMAGE_DEPENDS_<type>. При наличии классов с пользовательскими типами образов их следует обновить.
Добавлена поддержка OpenSSL 1.1, однако 1.0.x продолжает по умолчанию использоваться в переменной PREFERRED_VERSION. Это сохранено из-за остающихся проблем совместимости с другими программами. Переменная PROVIDES в задании openssl 1.0 сейчас включает openssl10 как маркер, который может использоваться DEPENDS в заданиях, собирающих программы, зависимые от OpenSSL 1.0.
Для согласованного поведения опций BitBake -r и -R (prefile и postfile), используемых для чтения или пост-чтения дополнительного конфигурационного файла из командной строки, они сейчас действуют лишь в текущей команде BitBake command. раньше указанные опции BitBake сохранялись при следующих вызовах.

4.13. Переход на YP 2.5

В этом разделе рассмотрен переход на YP 2.5 с предыдущего выпуска.

4.13.1. Изменения в пакетах

bind-libs — библиотеки подготавливаются заданием bind в отдельном пакете bind-libs.
libfm-gtk — привязки libfm GTK+ перенесены в отдельный пакет libfm-gtk.
flex-libfl — задание flex выделено из libfl в пакет flex-libfl для снижения числа зависимостей при установке только библиотеки.
grub-efi — конфигурация grub-efi перенесена в отдельное задание grub-bootconf. Однако зависимость от grub-efi указывается через провайдера virtual/grub-bootconf, что позволяет иметь свое задание для обеспечения зависимости. Можно использовать файл добавления BitBake для возврата конфигурации в задание grub-efi.
Поддержка устаревших хранилищ пакетов armv7a удалена для перехода с armv7a на armv7a-vfp-neon в хранилищах пакетов, который раньше включался переменной PKGARCHCOMPAT_ARMV7A. Переход произошел в 2011 г. и активные хранилища пакетов должны быть обновлены с указанием новых имен.

4.13.2. Удаленные задания

gcc — версия 6.4 заменена 7.x.
gst-player переименовано в gst-examples.
hostap-utils — пакет устарел.
latencytop больше не поддерживается (последний выпуск был в 2009 г.).
libpfm4 требовалось лишь удаленному заданию oprofile.
linux-yocto — версии 4.4, 4.9, 4.10 удалены, версии 4.12, 4.14, 4.15 сохраняются.
man заменено современным man-db
mkelfimage — программа удалена из проекта coreboot и больше не нужна после удаления типа образов ELF.
nativesdk-postinst-intercept не поддерживается.
neon — программа не поддерживается и больше не нужна в OpenEmbedded-Core.
oprofile — функциональность заменена perf, а совместимость с musl может быть затруднена.
pax — программа устарела.
stat — программа не развивается, а функции stat обеспечивает пакет coreutils.
zisofs-tools-native больше не требуется после исключения сжатых образов ISO.

4.13.3. Изменения сценариев и инструментов

yocto-bsp, yocto-kernel, yocto-layer, ранее входившие в poky, но не в OpenEmbedded-Core, удалены. Эти сценарии устарели и не поддерживаются, что во многих случаях ограничивало их применимость. Команда bitbake-layers create-layer служит их прямой заменой для yocto-layer(см. раздел BSP Kernel Recipe Example [6]).
devtool finish сейчас завершает работу с ошибкой при наличии непредставленных изменений или в процессе выполнения rebase в репозитории задания. Причиной ошибки могут быть незафиксированные изменения, не включенные в обновления к исправлениям, которые применены заданием. Если эти изменения несущественны, можно форсировать выполнение команды с помощью опции -f или —force.
scripts/oe-setup-rpmrepo — функциональность заменена командой bitbake package-index.
scripts/test-dependencies.sh — устарел и заменен функциональностью sysroots для заданий, добавленной YP 2.4.

4.13.4. BitBake

Изменена опция --runall, которая имеет 2 варианта поведения:

- вариант A — для данной цели (набора целей) просматривается граф задач и задача X запускается лишь при ее наличии и включении в сборку.
- вариант B — для данной цели (набора целей) просматривается граф задач и задача X запускается, если любое задание в графе задач имеет такую цель, даже если этого задания нет в исходном графе задач.

Опция --runall сейчас работает по варианту B, а ранее работала подобно варианту A. Опция --runonly добавлена для сохранения возможности использовать вариант A.

Удалены несколько явных задач, выполнявшихся для всех заданий в дереве зависимостей (например, fetchall, checkuriallи все задачи классовdistrodata и archiver). Имеется опция BitBake, позволяющая выполнить это для любой задачи. Например, bitbake <target> -c fetchall следует заменить на bitbake <target> —runall=fetch.

4.13.5. Изменения Python и Python 3

Управляемые сценариями файлы python-*-manifest.inc,применявшиеся для генерации пакетовPython и Python 3, заменены файлом JSON для удобства чтения и поддержки. Доступна новая задача для сопровождающих задания Python, которая переключает на файл JSON при переходе на новые версии Python. Файл можно редактировать напрямую вместо редактирования сценария и использования его для обновления файла.

Еще одно изменение, которое следует отметить, связано с тем, что задания Python больше не имеют провайдеров во время сборки пакетов. Это предполагает, что python является одним из пакетов, обеспечиваемых заданием Python. Можно больше не запускать bitbake python-foo и не иметь DEPENDS для python-foo, но нужно добавить IMAGE_INSTALL_append = » python-foo» или RDEPENDS_${PN} = «python-foo».

Поведение прежних провайдеров при сборке было причудой способа создания манифестов Python. Более подробные сведения об изменениях доступны по ссылке.

4.13.6. Прочие изменения

Класс kernel поддерживает сборку пакетов для нескольких ядер. Если задание для ядра или файл .bbappend включает упаковку, следует заменить ссылку на ядро в именах пакетов значением ${KERNEL_PACKAGE_NAME}. Например, при запрете автоматической установки ядра с помощью RDEPENDS_kernel-base
= «» можно избежать предупреждений, задав RDEPENDS_${KERNEL_PACKAGE_NAME}-base= «».
Класс buildhistory по умолчанию фиксирует изменения в репозитории и больше не нужно задавать BUILDHISTORY_COMMIT = «1». Если нужно отключить фиксацию, установите BUILDHISTORY_COMMIT = «0».
Эталонная машина beaglebone переименована в beaglebone-yocto. BSP beaglebone-yocto является эталонной реализацией, использующей лишь компоненты OpenEmbedded-Core и meta-yocto-bsp, тогда как Texas Instruments поддерживает полнофункциональный BSP на уровне meta-ti. Переименование избавило от имевшегося конфликта имен двух BSP.
Класс update-alternatives больше не работает со сценариями инициализации SysV, поскольку это стало проблематичным. Задание sysklogd больше не применяет update-alternatives по причине несовместимости с другими реализациями.
По умолчанию класс cmake использует при сборке пакетов ninja вместо makeдля повышения производительности сборки. Если задание не работает с ninja, можно установить OECMAKE_GENERATOR = "Unix Makefiles" для возврата к make.
Ранее отмененные функции base_* удалены с заменами из meta/lib/oe и bitbake/lib/bb. Эти функции обычно использовались в заданиях и классах и все ссылки на удаленные функции следует изменить в соответствии с приведенной ниже таблицей.

Удалено	Замена
base_path_join()	oe.path.join()
base_path_relative()	oe.path.relative()
base_path_out()	oe.path.format_display()
base_read_file()	oe.utils.read_file()
base_ifelse()	oe.utils.ifelse()
base_conditional()	oe.utils.conditional()
base_less_or_equal()	oe.utils.less_or_equal()
base_version_less_or_equal()	oe.utils.version_less_or_equal()
base_contains()	bb.utils.contains()
base_both_contain()	oe.utils.both_contain()
base_prune_suffix()	oe.utils.prune_suffix()
oe_filter()	oe.utils.str_filter()
oe_filter_out()	oe.utils.str_filter_out() (или оператор _remove).

Использование exit 1 для явной отсрочки сценария пост-установки до первой перезагрузки отменено, поскольку этот неочевидный механизм может скрывать ошибки. Если во время создания rootfsнужно явно отложить пост-установку до первой перезагрузки, следует использовать pkg_postinst_ontarget() или вызов postinst-intercepts defer_to_first_boot from pkg_postinst(). Любой отказ сценария pkg_postinst(),включая exit 1,будет вызывать предупреждение при работе задачиdo_rootfs.

Дополнительная информация приведена в разделе Post-Installation Scripts [2].
Образы типа elf исключены, поскольку инструмент mkelfimage,который нужен для их создания, больше не поддерживается вcoreboot и требует обновления при каждом изменении binutils.
Удалена поддержка сжатия образов .iso (ранее включаемая через COMPRESSISO = "1"). Инструменты пользовательского пространства (zisofs-tools) не поддерживаются, а squashfs обеспечивает более эффективное сжатие. Для сборки live-образов с компрессией squashfs+lz4 следует задать LIVE_ROOTFS_TYPE = "squashfs-lz4" и включить live в IMAGE_FSTYPES.
Заданием с безусловной зависимостью от libpam было лишь buildable с pam в DISTRO_FEATURES. Если зависимость не является обязательной, лучше сделать ее условной по наличию pam в DISTRO_FEATURES.
Для машин на базе EFI загрузчик (по умолчанию grub-efi) устанавливается в образе как /boot. Можно использовать Wic для разделения загрузчика на разделы boot и rootfs.
Patch-файлы, контекст которых не имеет точного соответствия (исправление дает fuzz при наложении), будут вызывать предупреждения. Пример доступен по ссылке.
Предполагается, что уровни устанавливают LAYERSERIES_COMPAT_layername в соответствии с версией OpenEmbedded-Core, с которой они совместимы. Это указывается как кодовое имя с использованием пробелов для разделения значений (например, «rocko sumo»). Если уровень не устанавливает LAYERSERIES_COMPAT_layername, выводится предупреждение. Если уровень устанавливает значение, не включающее текущей версии («sumo» для выпуска 2.5), выдается ошибка.
В переменной окружения TZ устанавливается значение UTC в среде сборки для предотвращения проблем воспроизводимости в некоторых заданиях.

4.14. Переход на YP 2.6

В этом разделе рассмотрен переход на YP 2.6 с предыдущего выпуска.

4.14.1. По умолчанию применяется GCC 8.2

GNU Compiler Collection версии 8.2 сейчас по умолчанию используется для компиляции. Дополнительная информация об изменениях в выпуске GCC 8.x доступна по ссылке https://gcc.gnu.org/gcc-8/changes.html. Для случаев потребности в компиляторе версии 7.x сохранен GCC 7.3. Этот компилятор можно выбрать, установив в конфигурации для переменной GCCVERSION значение «7.%».

4.14.2. Удаленные задания

beecrypt не требуется в связи с переходом на RPM 4.
bigreqsproto заменено xorgproto.
calibrateproto удалено с заменой на xinput.
compositeproto, damageproto, dmxproto, dri2proto, dri3proto заменены xorgproto.
eee-acpi-scripts устарело.
fixesproto, fontsproto заменены xorgproto.
fstests устарело.
gccmakedep больше не применяется.
glproto заменено xorgproto.
gnome-desktop3 больше нет требуется. Перенесено в meta-oe.
icon-naming-utils больше не применяется в результате удаления темы Sato в 2016 г.
inputproto, kbproto заменены xorgproto.
libusb-compat устарело.
libuser устарело.
libnfsidmap больше не требуется с переходом на nfs-utils 2.2.1.
libxcalibrate больше не требуется.
mktemp устарело. Команда mktemp предоставляется заданиями busybox и coreutils.
ossp-uuid не будет поддерживаться и в основном заменено uuid.h в util-linux.
pax-utils больше не нужно. Прежние тесты QA использовали это задание при сборке.
pcmciautils устарело.
pixz больше не требуется, поскольку xz поддерживает многопотоковое сжатие.
presentproto, randrproto, recordproto, renderproto, resourceproto, scrnsaverproto заменены xorgproto.
trace-cmd устарело, функциональность заменена perf.
wireless-tools устарело и заменено iw.
xcmiscprotoзамененоxorgproto.
xextproto заменено xorgproto.
xf86dgaproto заменено xorgproto.
xf86driproto заменено xorgproto.
xf86miscproto заменено xorgproto.
xf86-video-omapfb устарело, взамен используется драйвер ядра modesetting.
xf86-video-omap устарело, взамен используется драйвер ядра modesetting.
xf86vidmodeproto заменено xorgproto.
xineramaproto заменено xorgproto.
xproto заменено xorgproto.
yasm больше не требуется, поскольку прежнее использование заменено nasm.

4.14.3. Изменения в пакетах

cmake — файлы cmake.m4 и инструментарий перенесены в основной пакет.
iptables — модули размещены в отдельных пакетах.
alsa-lib — библиотека libasound перенесена в основной пакет alsa-lib из libasound.
glibc — libnss-db теперь в своем пакете вместе со сценарием /var/db/makedbs.sh для обновления баз данных.
python и python3 — основной пакет удален из задания. Нужно установить конкретные пакеты python-modules или python3-modules для остального.
systemtap — systemtap-exporter перемещен в отдельный пакет.

4.14.4. Зависимости протокола XOrg

Находящиеся в разработке репозитории *proto объединены в xorgproto, поэтому соответствующие задания также были объединены в xorgproto. Задания, зависимые от старых заданий *proto,следует исправить с заменой наxorgproto. Имена удаленных при объединении заданий приведены в параграфе 4.14.2. Удаленные задания.

4.14.5. Предотвращение зависимости сборщиков в `do_configure`

Ранее для заданий Python, наследующих классы distutils и distutils3,при выполнении задачиdo_configure можно было выполнить зависимости, заданные в setup.py,если они не были указаны в sysroot (т. е. задания, указывающие зависимости не были включены в DEPENDS).

Это изменение влияет не только на упомянутые классы distutils и distutils3,но и на все задания, наследующие distutils*, например, на задания setuptools и setuptools3.

Извлечение типов зависимостей, не указанных в sysroot, снижает производительность сборки, поэтому такая выборка была явно отключена. В результате все отсутствующие в заданиях Python зависимости при использовании этих классов будут давать ошибку в задаче do_configure.

4.14.6. Решена проблема настройки аудита в `linux-yocto`

В результате ошибки функции аудита в ядре не записывались предупреждения при сборке. Сейчас эта проблема решена. Предупреждения можно видеть в пользовательских конфигурациях с заданием для ядра linux-yocto.

4.14.7. Именование элементов образов и ядер

Имена переменных (например, IMAGE_NAME) используют новую переменную IMAGE_VERSION_SUFFIXвместо DATETIME,что упрощает изменения. Переменная IMAGE_VERSION_SUFFIX задается файлом bitbake.conf в форме IMAGE_VERSION_SUFFIX = «-${DATETIME}».

Имена некоторых переменных изменены для согласованности, как показано в таблице.

Старое имя	Новое имя
KERNEL_IMAGE_BASE_NAME	KERNEL_IMAGE_NAME
KERNEL_IMAGE_SYMLINK_NAME	KERNEL_IMAGE_LINK_NAME
MODULE_TARBALL_BASE_NAME	MODULE_TARBALL_NAME
MODULE_TARBALL_SYMLINK_NAME	MODULE_TARBALL_LINK_NAME
INITRAMFS_BASE_NAME	INITRAMFS_NAME

Переменная MODULE_IMAGE_BASE_NAME удалена, имя архива контролируется напрямую переменной MODULE_TARBALL_NAME.
Переменные KERNEL_DTB_NAME и KERNEL_DTB_LINK_NAME добавлены для управления элементами дерева устройств ядра (DTB¹³) вместо переменных KERNEL_IMAGE_*.
Добавлены переменные KERNEL_FIT_NAME и KERNEL_FIT_LINK_NAME для задания имени плоского дерева образа (FIT¹⁴) для образов ядра подобно другим развернутым элементам.
Значения переменных MODULE_TARBALL_NAME и MODULE_TARBALL_LINK_NAME больше не включают префиксов module- и суффиксов .tgz. Эти части сейчас кодируются жестко для согласованности и другими переменными именования элементов.
Добавлена переменная INITRAMFS_LINK_NAME для контроля символьных ссылок подобно другим элементам.
INITRAMFS_NAME сейчас использует ${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX} вместо ${PV}-${PR}-${MACHINE}-${DATETIME} для соответствия другим переменным.

4.14.8. Отмена `SERIAL_CONSOLE`

Переменная SERIAL_CONSOLE функционально заменена переменной SERIAL_CONSOLES некоторое время назад. С выпуска YP 2.6 переменная SERIAL_CONSOLE отменена официально. SERIAL_CONSOLE будет работать как в прежних выпусках, но для совместимости с новыми версиями рекомендуется заменить ее на SERIAL_CONSOLES. Различия между этими переменными заключается в том, что в SERIAL_CONSOLES элементы записи разделяются точкой с запятой вместо пробела, а также возможно указание нескольких консолей, разделенных пробелами.

4.14.9. Сценарий настройки считает неизвестные опции ошибкой

Если конфигурационный сценарий находит незнакомую опцию, это вызывает ошибку a QA вместо предупреждения. Это может потребовать внесения изменений в имеющиеся задания.

4.14.10. Изменение переопределений

Удалены virtclass-native и virtclass-nativesdk, отмененные в 2012 г. с заменой на class-native и class-nativesdk. Переопределения virtclass-multilib- для multilib сохраняются.
Более высокий приоритет forcevariable по сравнению с libc был документирован достаточно давно, однако давняя причуда с установкой OVERRIDES давала переопределениям libc (например libc-glibc, libc-musl и т. п.) более высокий приоритет. Сейчас это устранено.

Это изменение не должно вызывать проблем, однако в некоторых необычных конфигурациях возможно иное поведение, нежели предполагалось ранее. Нужно проверить переопределения forcevariable и libc-* на пользовательских уровнях в части их осмысленности.
Удалено build-${BUILD_OS}, которое обычно имело форму build-linux, поскольку сборка в ОС хоста, отличной от последней версии Linux не поддерживается и не рекомендуется. Отказ от переопределения позволяет избежать ложного впечатления о поддержке других версий операционной системы.
Оператор _remove сохраняет пробелы, поэтому при указании списка удаляемых элементов следует помнить, что пробелы в начала и в конце не удаляются (см. примеры в разделе Removal (Override Style Syntax) [4]).

4.14.11. Конфигурация `systemd` выделена в `systemd-conf`

Конфигурация задания systemd перенесена в system-conf, что позволяет избавить systemd от машинозависимости при необходимости применить зависимую от машину конфигурацию (например, для машин qemu*). Задание включает:

     ${sysconfdir}/machine-id
     ${sysconfdir}/systemd/coredump.conf
     ${sysconfdir}/systemd/journald.conf
     ${sysconfdir}/systemd/logind.conf
     ${sysconfdir}/systemd/system.conf
     ${sysconfdir}/systemd/user.conf

Если ранее применялись файлы bbappend для добавления systemd с целью изменить какой-то из приведенных выше файлов, сейчас это нужно делать в задании systemd-conf.

4.14.12. Изменение автоматического тестирования

Удалена переменнаяTEST_IMAGE, которая при установке значения 1 включала автоматическое тестирование сборки образа. Сейчас вместо этого используется значение переменной TESTIMAGE_AUTO.
Наследование классов testimage и testsdk. Опыт диктует использование переменной IMAGE_CLASSES,а неINHERIT при наследовании классов testimage и testsdk для автоматического тестирования.

4.14.13. Изменение OpenSSL

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

При работе могут применяться обе версии библиотеки.

4.14.14.Изменение BitBake

Журнальный файл сервера bitbake-cookerdaemon.log всегда присутствует в каталоге сборки, а не в текущем каталоге.

4.14.15. Изменение защиты

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

4.14.16. Изменение пост-установки

Нужно явно указать задержку пост-установки до целевой платформы. Если нужно явно отложить пост-установку на целевой платформе до перезагрузки после инсталляции, следует использовать pkg_postinst_ontarget() или вызов postinst-intercepts defer_to_first_boot из pkg_postinst(). Любой отказ сценария pkg_postinst(), включая exit 1, будет вызывать ошибку задачи do_rootfs. Информация о пост-установке приведена в разделе Post-Installation Scripts [2].

4.14.17. Оптимизация на основе профилей Python 3

Задание python3 сейчас включает оптимизацию по профилю, что несколько увеличивает время сборки для повышения производительности работы на целевой платформе. Оптимизация включается лишь при поддержке текущей машиной MACHINE пользовательского режима эмуляции в QEMU («qemu-usermode» присутствует в MACHINE_FEATURES, как принято по умолчанию).

Если нужно отключить оптимизацию для любого значения MACHINE_FEATURES, следует убедиться в отсутствии pgo в переменной PACKAGECONFIG для задания python3. Это можно сделать, указав на уровне конфигурации PACKAGECONFIG_remove_pn-python3 = «pgo» или задав PACKAGECONFIG в файле добавления для python3.

4.14.18. Прочие изменения

По умолчанию используется набор инструкций Thumb-2 для armv7a и выше. При наличии заданий для сборки программ, которым нужен набор инструкций ARM, его можно задать в виде ARM_INSTRUCTION_SET = «arm».
run-postinsts больше не использует /etc/*-postinsts для dpkg/opkg, применяя
встроенную поддержку пост-установки. Поведение RPM не изменилось.
Переменные NOISO и NOHDD больше не применяются. Можно управлять сборкой образов *.iso и *.hddimg напрямую через переменную IMAGE_FSTYPES.
От сценария scripts/contrib/mkefidisk.sh отказались в пользу Wic.
Задание kernel-modules удалено из RRECOMMENDS для машин qemumips и qemumips64. Исключено также влияние файла x86-base.inc. Для машин genericx86 и genericx86-64 задание kernel-modules сохранено в переменной RRECOMMENDS.
Удалена переменная LGPLv2_WHITELIST_GPL-3.0.При наличии ее в конфигурации следует вместо нее установить или дополнить переменнуюWHITELIST_GPL-3.0.
${ASNEEDED} сейчас напрямую включается в переменную TARGET_LDFLAGS. Другие определения из meta/conf/distro/include/as-needed.inc перенесены в соответствующие задания.
Поддержка ключей DSA для хоста исключена из заданий OpenSSH. Если такие ключи продолжают использоваться, следует перейти на более защищенные алгоритмы, рекомендуемые OpenSSH.
Задание dhcp сейчас применяет конфигурационный файл dhcpd6.conf в dhcpd6.service для IPv6 DHCP вместо файла dhcpd.conf, который сейчас служит для IPv4.

4.15. Переход на YP 2.7

В этом разделе рассмотрен переход на YP 2.7 с предыдущего выпуска.

4.15.1. BitBake

BitBake проверяет анонимные (anonymous) и чистые (pure) функции Python (например, def funcname:) в метаданных на предмет использования символов табуляции с выдачей предупреждений при их наличии.
Bitbake проверяет BBFILE_COLLECTIONS на предмет дубликатов с возвратом ошибки при обнаружении.

4.15.2. Исключена поддержка Eclipse™

Поддержка Eclipse IDE исключена, но сохраняется для выпусков до 2.7. Выпуск 2.7 не включает плагин Eclipse Yocto.

4.15.3. Разделение системной и пользовательской части в `qemu-native`

Системная и пользовательская часть задания qemu-native разделены. Задание qemu-native обеспечивает пользовательские компоненты, а qemu-system-native — системные. При наличии заданий, зависящих от функциональности системы эмуляции QEMU при сборке, следует заменить в них qemu-native на qemu-system-native.

4.15.4. Удаление файла `upstream-tracking.inc`

Ранее отмененный файл upstream-tracking.inc удален. Все переменные UPSTREAM_TRACKING* устанавливаются в соответствующих заданиях. Следует удалить в своей конфигурации все ссылки на файл upstream-tracking.inc.

4.15.5. Удаление переменной `DISTRO_FEATURES_LIBC`

Переменная DISTRO_FEATURES_LIBC больше не применяется. Возможность настройки glibc с помощью kconfig была удалена некоторое время назад и свойства libc-* утратили силу. Следует удалить DISTRO_FEATURES_LIBC из своих заданий.

4.15.6. Корректировки значений лицензий

Socat — значение LICENSE изменено на GPLv2 вместо GPLv2+.
libgfortran — задана лицензия GPL-3.0-with-GCC-exception.
elfutils — удалено значение Elfutils-Exception и установлено GPLv2 для общих библиотек.

4.15.7. Изменение подготовки пакетов

bind — двоичный файл nsupdate перенесен в пакет bind-utils.
Разделение отладки, принятое по умолчанию, было изменено для создания отдельных пакетов с исходным кодом (package_name-dbg и package_name-src). При использовании dbg-pkgs в IMAGE_FEATURES для получения отладочных символов можно добавить в переменную src-pkgs,если нужны исходные коды. Пакеты с исходным кодом по умолчанию сохранены вSDK, если в SDKIMAGE_FEATURES не задано их исключение.
Монтирование с помощью util-linux. Файл /etc/default/mountall перенесен в субпакет mount.
Разделение двоичных файлов util-linux — сейчас каждый двоичный исполняемый файл выделен в свой пакет для более тонкого управления. Основной пакет util-linux втягивает отдельные двоичные пакеты с помощью переменных RRECOMMENDS и RDEPENDS. В результате образы не будут иметь видимых изменений, пока не установлена переменная NO_RECOMMENDATIONS.
netbase/base-files — файл /etc/hosts перенесен из netbase в base-files.
tzdata — основной пакет преобразован в пустой мета-пакет, который по умолчанию втягивает все пакеты tzdata.
lrzsz удален из packagegroup-self-hosted и packagegroup-core-tools-testapps. Потребность в X/Y/ZModem маловероятна в современных системах. Если вы включали пакет lrzsz на основе упомянутых групп, потребуется добавить его явно.

4.15.8. Удаленные задания

gcc — задания версии 7.3 исключены, версия 8.3 сохраняется.
linux-yocto — исключены задания версий 4.14 и 4.18, версии 4.19 и 5.0 сохранены.
go — исключены задания версии 1.9, версии 1.11 и 1.12 сохранены.
xvideo-tests устарело.
libart-lgpl устарело.
gtk-icon-utils-native сейчас предоставляется заданием gtk+3-native
gcc-cross-initial больше не нужно, взамен используется gcc-cross/gcc-crosssdk.
gcc-crosssdk-initial больше не нужно, взамен используется gcc-cross/gcc-crosssdk.
glibc-initial удалено, поскольку преимущества наличия для site_config перевешиваются сложностью сборки.

4.15.9. Удаленные классы

distutils-tools никогда не использовался.
bugzilla.bbclass устарел.
distrodata — функциональность заменена более современной реализацией на основе tinfoil.

4.15.10. Прочие изменения

Каталог distro репозитория Poky удален из каталога сценариев верхнего уровня.
Perl сейчас выполняет сборку для целевых систем с использованием perl-cross для улучшения сопровождаемости и повышения производительности сборки. Это изменение не должно вызывать проблем, если вы не меняли сильно свое задание Perl.
arm-tunes — удалена опция -march, если уже добавлено mcpu.
update-alternatives — файл преобразования переименован в PACKAGE_PREPROCESS_FUNCS.
base/pixbufcache - удален устаревший код sstatecompletions.
native class — включена обработка RDEPENDS.
inetutils - в задании отключена оболочка rsh.

Продолжение

1Windows Subsystem for Linux.

2Network File System — сетевая файловая система.

3Software Development Kit — комплект для разработки программ.

4Quality Assurance — гарантия (контроль) качества.

5Board Support Package.

6В установленном по умолчанию файле local.conf эти строки присутствуют, поэтому при сборке образов для систем без монитора следует их закомментировать.

7Filesystem Hierarchy Standard — стандарт иерархии файловых систем.

8Application Development Toolkit.

9GLib Introspective Repository — репозиторий самоанализа Glib.

10В двоичном файле отсутствует GNU_HASH.

11Position Independent Executables — независимые от положения исполняемые файлы.

12Return Oriented Programming — ориентированное на возврат программирование.

13Device Tree Binary.

14Flattened image tree.

Рубрика: Linux | Комментарии отключены

Разработка приложений Yocto Project и eSDK

Опубликовано 18.12.2019 автором Nikolai Malykh

PDF

Scott Rifenbark

Scotty’s Documentation Services, INC

<srifenbark@gmail.com>

Permission is granted to copy, distribute and/or modify this document under the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons.

Глава 1. Начальные сведения

1.1. Ведение

В этом документе описано использование стандартных и расширяемых SDK¹ Yocto Project (YP) для разработки приложений и образов. До выпуска YP 2.0 разработка приложений выполнялась с использованием ADT², инструментов кросс-разработки и других средств. В выпуске YP 2.1 разработка была перенесена в расширяемый SDK с большим набором инструментов и стандартный SDK. Все варианты SDK включают:

инструменты кросс-разработки — компилятор, отладчик и другие инструменты;
библиотеки, заголовочные файлы и символы для конкретных образов;
сценарий организации среды — файлы *.sh, запускаемые однократно для организации среды кросс-разработки путем определения переменных и подготовки SDK к работе.

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

Можно применять SDK для независимой разработки и тестирования кода, предназначенного для целевой машины. SDK являются самодостаточными, двоичные файлы компонуются со своей копией libc, что обеспечивает независимость от целевой системы. Для достижения этого настраивается указатель на динамический загрузчик во время установки, поскольку путь не может быть изменен динамически. Это является причиной создания архивов populate_sdk и populate_sdk_ext.

Другим свойством SDK является создание единственного набора двоичных инструментов кросс-компиляции для данной архитектуры. Это основано на том, что целевое оборудование может быть указано компилятору gcc как набор опций, устанавливаемых сценарием настройки среды и содержащих такие переменные, как CC и LD. Такой подход снижает размер инструментария, однако следует понимать, что для каждой цели все равно требуется sysroot, поскольку двоичные файлы зависят от платформы.

Среда разработки SDK содержит две основных компоненты.

Автономный SDK, содержащий инструменты кросс-разработки для конкретной архитектуры и соответствующие sysroot (для себя и целевой платформы), созданные системой сборки OE (например, SDK). Инструменты и sysroot базируются на метаданных конфигурации и расширений, что обеспечивает возможность кросс-разработки на хосте для целевой платформы. Расширяемый SDK содержит также инструмент devtool.
Эмулятор QEMU³, позволяющий имитировать целевое оборудование. Строго говоря, QEMU не является частью SDK и эмулятор нужно собирать и включать отдельно. Однако он играет важную роль в процессе разработки.

Стандартный и расширяемый SDK имеют много общего, однако в eSDK включены мощные средства разработки. В таблице можно увидеть основные характеристики обоих вариантов.

Свойство	Стандартный SDK	Расширяемый SDK
Инструменты	+	+⁴
Отладчик	+	+⁴
Размер	От 100 Мбайт	От 1 Гбайт (от 300 Мбайт в сокращенном варианте)
`devtool`	—	+
Сборка образов	—	+
Обновляемость	—	+
Управление Sysroot⁵	—	+
Установленные пакеты	—⁶	+⁷
Результат	Пакеты	Общее состояние

1.1.1. Инструменты кросс-разработки

Инструментарий кросс —разработки включает кросс-компилятор, кросс-компоновщик и кросс-отладчик, которые применяются при разработке пользовательских приложений для целевого оборудования. Расширяемый SDK включает также программу devtool. Инструментарий создается сценарием установки SDK или через каталог сборки с конфигурацией метаданных и расширений для целевого устройства. Кросс-инструменты работают с соответствующей файловой системой sysroot.

1.1.2. Sysroot

Естественная и целевая система sysroot содержат заголовочные файлы и библиотеки для создания двоичных файлов, работающих на целевой архитектуре. Целевая система sysroot основана на образе корневой файловой системы целевой платформы, создаваемом системой сборки OE с использованием тех же конфигурации метаданных, что и при сборке кросс-инструментов.

1.1.3. Эмулятор QEMU

Эмулятор QEMU позволяет имитировать оборудования для запуска образа или приложения. QEMU не является частью SDK и доступен несколькими способами:

клонирование репозитория poky Git для создания дерева источников;
загрузка и распаковка выпуска YP для создания дерево источников;
установка архива кросс инструментов.

1.2. Модель разработки в SDK

Процесс разработки с использованием SDK показан на рисунке.

SDK устанавливается на любую машину и может применяться для разработки приложений, образов и ядер. Важно то, что машину с SDK не требуется связывать с машиной YP. Разработчик может независимо компилировать и тестировать объекты на своей машине, а по готовности включать их в образ, просто делая доступными для машины YP. Когда объект становится доступным, образ можно собрать заново с использованием YP.

Для работы нужно выполнить перечисленные ниже действия.

Установка SDK для целевого оборудования, как описано в параграфе 3.2. Установка SDK.
Загрузка или сборка целевого образа. YP поддерживает разную архитектуру и имеет множество собранных образов ядер и корневых файловых систем. Для разработки приложений под целевое оборудование следует выбрать целевую машину в разделе machines и загрузить нужные образы ядра и корневой файловой системы.

При разработке приложений в запуском в эмуляторе QEMU следует выбрать область machines/qemu и найти там файлы для целевой архитектуры (например, qemux86_64 для 45-битовых платформ Intel®). Для использования корневой файловой системы в QEMU ее потребуется распаковать (A.3. Извлечение корневой файловой системы.
Разработка и тестирование приложения. После выполнения предыдущих пунктов можно начинать разработку. Если нужно отдельно установить QEMU, можно найти нужный файл на сайте QEMU. Работа с эмулятором описана в разделе Using the Quick EMUlator (QEMU) [1].

Глава 2. Использование eSDK

В этой главе описана установка расширяемого SDK и работа с ним, а также функции devtool. Расширяемый SDK упрощает добавление в образ приложений и библиотек, менять источники имеющихся компонент, тестировать изменения на целевой платформе, а также упрощает интеграцию с системой сборки OE. Сравнение возможностей стандартного и расширяемого SDK приведено в разделе 1.1. Ведение.

В дополнение к функциональности devtool можно использовать инструменты напрямую (Глава 4. Использование инструментов SDK).

2.1. Что такое eSDK?

Расширяемый SDK предоставляет инструменты кросс-разработки и библиотеки, адаптированные к содержимому конкретного образа. Дополнением является мощный инструмент devtool, адаптированный для среды YP. Установленный eSDK включает множество файлов и каталогов, а также сценарий организации среды, конфигурационные файлы, встроенную систему сборки и devtool.

2.2. Установка eSDK

Первым делом нужно установить SDK на сборочный хост с помощью сценария *.sh. Можно загрузить архив установщика, включающий собранные инструменты, сценарий runqemu, систему сборки, devtool, и файлы поддержки из подходящего каталога
toolchain в списке выпусков. Инструменты доступны для 32- и 64-битовой архитектуры. Инструменты YP основаны на образах core-image-sato и core-image-minimal и включают библиотеки для разработки.

Имена архивов с установочными сценариями представляют сначала хост-систему, а затем следует строка представления целевой архитектуры. Для eSDK в имени сценария присутствует -ext. Базовый формат имеет вид poky-glibc-host_system—image_type—arch-toolchain-ext-release_version.sh, где строка host_system указывает систему разработки (i686 или x86_64), image_type указывает образ, для которого будет собран SDK (core-image-sato или core-image-minimal), arch задает целевую архитектуру (aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400 или cortexa8hf-neon), release_version — номер выпуска YP (3.0, 3.0+snapshot). Например, установщик для 64-битовой хост-системы и целевой архитектуры i586-tuned на основе образа core-image-sato и текущего выпуска 3.0 будет называться poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-3.0.sh.

Можно также загрузить SDK и собрать установщик, как описано в приложении A.2. Сборка установщика SDK.

SDK и инструменты самодостаточны ии устанавливаются в каталог poky_sdk внутри домашнего каталога, хотя можно выбрать иное место для установки. Однако местоположение SDK должна быть доступно для записи всем пользователям SDK. Ниже приведена команда для запуска установщика на 64-битовой системе x86 для 64-битовой архитектуры x86 с установкой SDK в каталог ~/Downloads/. Если у вас нет полномочий записи в каталог установки SDK, программа сообщит об этом и завершит работу.

     $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
     Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
     ==========================================================================
     Enter target directory for SDK (default: ~/poky_sdk):
     You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
     Extracting SDK..............done
     Setting it up...
     Extracting buildtools...
     Preparing build system...
     Parsing recipes: 100% |##################################################################| Time: 0:00:52
     Initialising tasks: 100% |###############################################################| Time: 0:00:00
     Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00
     Loading cache: 100% |####################################################################| Time: 0:00:00
     Initialising tasks: 100% |###############################################################| Time: 0:00:00
     done
     SDK has been successfully set up and is ready to be used.
     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
      $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux

2.3. Запуск сценария организации среды eSDK

После установки SDK нужно запустить сценарий организации среды SDK, чтобы можно было начать работу. Сценарий размещается в каталоге, указанном при установке SDK (по умолчанию poky_sdk). Перед запуском сценария следует проверить его соответствие архитектуре, для которой планируется разработка. Имена сценариев организации среды начинаются с environment-setup и включают целевую архитектуру. Ниже приведен пример запуска сценария для целевой машины IA с архитектурой i586.

$ cd /home/scottrif/poky_sdk
$ source environment-setup-core2-64-poky-linux
 SDK environment now set up; additionally you may now run devtool to perform development tasks.
 Run devtool --help for further details.

Сценарий определяет переменные окружения для работы SDK (например, PATH, CC, LD и т. п.), список которых можно увидеть в файле сценария.

2.4. Использование `devtool` в процессах SDK

Одним из основных инструментов eSDK является команда devtool, обеспечивающая
возможности сборки, тестирования и подготовки пакетов для программ в eSDK, а также их встраивание в образы, создаваемые системой сборки OE. Применение devtool не ограничивается eSDK и программу можно использовать для разработки любых проектов, вывод которых должен стать частью образа в системе сборки.

Команды devtool организационно похожи на команды Git, помотреть список команд можно с помощью devtool —help. Подробная информация о devtool приведена в разделе devtool Quick Reference [2]. Тремя основными командами devtool для начала работы служат:

devtool add — добавляет в сборку новую программу;
devtool modify — устанавливает среду для изменения источников имеющихся компонент;
devtool upgrade — обновляет имеющееся задание для сборки с обновленными исходными файлами.

Как и в системе сборки, задания представляют программные пакеты в devtool. Команда devtool add автоматически создает задание, с devtool modify используется имеющееся задание для указания местоположения источников и способа их изменения (patch). В обоих случаях среда выполнения организуется так, чтобы при сборке задания использовалось контролируемое дерево источников, что позволяет вносить нужные изменения в код. По умолчанию новые задания и исходный код помещаются в каталог workspace в дереве SDK.

2.4.1. Добавление приложения с помощью devtool add

Команда devtool add создает новое задание на основе имеющихся исходных кодов, используя уровень workspace, как и многие другие команды devtool. Команда достаточно гибко позволяет извлекать исходный код в workspace или локальный репозиторий Git, а также использовать имеющийся код, извлекать который не нужно. В зависимости от конкретной ситуации применяются разные аргументы и опции devtool add, как описано ниже и показано на рисунке.

Генерация нового задания. В общей среде разработки участники процесса обычно отвечают за свои области исходного кода. Для работы нужен доступ к коду, заданию и рабочей области. В верхней части рисунка показано 3 варианта использования devtool add для генерации задания на основе имеющихся источников.

- Левый вариант представляет ситуацию где исходные коды не присутствуют локально и их нужно извлечь. Здесь извлечение кода выполняется в workspace. Команда devtool add recipe fetchuri извлечет файлы исходного кода в локальный репозиторий Git в каталоге sources, затем создаст в workspace задание и файл добавления с указанным именем. Если параметр recipe не указан, команда попытается самостоятельно определить имя задания.

- Средний вариант представляет случай, когда исходные коды не присутствуют локально и их нужно извлечь, но разместить за пределами локального каталога workspace. Команда devtool add recipe srctree fetchuri создаст локальный репозиторий Git в каталоге, указанном параметром srctree. Также будут созданы файлы задания (recipe) и связанного с ним дополнения.

- Правый вариант соответствует случаю, когда исходные коды уже имеются за пределами workspace. Команда devtool add recipe srctree проверит исходный код в srctree и создаст файлы задания (recipe) и дополнения в workspace.

Редактирование задания с помощью команды edit-recipe позволяет использовать редактор, указанный в переменной окружения $EDITOR.
Сборка задания или повторная сборка образа выполняется с помощью команды devtool build recipe или devtool build-image image.
Развертывание результатов сборки после команды devtool build для проверки работоспособности на целевой системе или в эмуляторе QEMU. При развертывании образа предполагается наличие в этом образе SSH, а при использовании реального оборудования — доступ к платформе через сеть с хоста разработки. Для развертывания образа служит команда devtool deploy-target recipe target, где параметр target указывает целевую систему. Для переноса образа на физическую платформу потребуются дополнительные команды в зависимости от конкретного устройства.
Завершение работы с заданием по команде devtool finish recipe layer создает все нужные правки (patch) соответствующие фиксациям (commit) в локальном репозитории Git, переносит задание на постоянный уровень (layer) и настраивает задание для обычной сборки вместо использования workspace. Восстанавливаются также состояния стандартных уровней и дерева источников. При необходимости можно воспользоваться командой devtool reset для возврата к работе с заданием.

2.4.2. Изменение кода с помощью `devtool modify`

Команда devtool modify готовит способ работы с имеющимся кодом, для которого уже есть локальное задание для сборки программ. Команда позволяет извлекать код из восходящего источника, указывать имеющееся задание, а также отслеживать и извлекать любые файлы исправлений (patch) от других разработчиков, связанные с заданием. В зависимости от конкретной ситуации применяются разные аргументы и опции devtool modify, как описано ниже и показано на рисунке.

Подготовка к изменению кода показана в верхней части рисунка в предположении, что задание размещено локально на уровне, не входящем в workspace, а исходные файлы размещены в несжатом виде локально или в восходящем репозитории.
- Левый вариант показывает случай, когда исходных кодов нет локально и нужно их извлечь. По умолчанию полученные файлы записываются в workspace. Задание размещается на своем уровне за пределами workspace. Команда devtool modify recipe находит задание и извлекает файлы исходного кода, используя переменную SRC_URI для поиска исходного кода и локальных исправлений (patch) от других разработчиков. Здесь не используется аргумент srctree, поэтому команда devtool modify по умолчанию извлекает файлы, указанные SRC_URI, в локальный репозиторий Git внутри workspace. В результате выполнения команды исходный код и файлы дополнения размещаются в workspace, а задание — на своем уровне.
  
  При наличии локальных файлов, не являющихся исправлениями (файлы, указанные с file:// в переменной SRC_URI, за исключением *.patch и *.diff) эти файлы копируются в каталог oe-local-files созданного дерева исходного кода, где эти файлы можно редактировать. Внесенные в эти файлы изменения или добавления будут включены в следующую сборку вместе с другими изменениями исходного кода.

- Средний вариант показывает случай, когда исходных кодов нет локально и нужно их извлечь, но они помещаются в локальный репозиторий Git, указанный параметром srctree. Команда devtool modify recipe srctree указывает изменяемое задание и локальный каталог для записи извлеченных файлов. В параметре srctree не допускается указание URL.

Переменная SRC_URI указывает местоположение всех локальных файлов, связанных с исправлениями (patch), остальные локальные файлы копируются в каталог oe-local-files созданного дерева кодов. Внутри workspace команда создает файл дополнения для задания, само задание сохраняется в исходном месте, а исходные коды помещаются в каталог, указанный srctree.

- Правый вариант относится к случаю, когда исходные коды уже имеются локально (srctree) в виде репозитория Git за пределами workspace. Задание размещается локально на своем уровне. Команда devtool modify -n recipe srctree использует опцию -n для указания того, что исходный код не нужно извлекать, а srctree задает его местоположение. Если каталог oe-local-files уже имеется в дереве кода и содержит файлы, не являющиеся правками (patch), эти файлы будут использованы. Однако если этого каталога нет и была использована команда devtool, эти файлы будут удалены.

По завершении команды devtool modify будет создан лишь файл дополнения в workspace, а задание и исходные коды сохранятся на своих местах.

Редактирование задания по завершении команды devtool modify возможно с помощью любого редактора.
Сборка задания или повторная сборка образа выполняется с помощью команды devtool build recipe или devtool build-image image.
Развертывание результатов сборки после команды devtool build для проверки работоспособности на целевой системе или в эмулятореQEMU. При развертывании образа предполагается наличие в этом образе SSH, а при использовании реального оборудования — доступ к платформе через сеть с хоста разработки. Для развертывания образа служит команда devtool deploy-target recipe target, где параметр target указывает целевую систему. Для переноса образа на физическую платформу потребуются дополнительные команды в зависимости от конкретного устройства.
Завершение работы с заданием по команде devtool finish recipe layer создает все нужные правки (patch) соответствующие фиксациям (commit) в локальном репозитории Git, переносит задание на постоянный уровень (layer) и настраивает задание для обычной сборки вместо использования workspace. Восстанавливаются также состояния стандартных уровней и дерева источников. При необходимости можно воспользоваться командой devtool reset для возврата к работе с заданием.

2.4.3. Использование `devtool upgrade` для обновления задания

Команда devtool upgrade обновляет имеющееся задание путем использования более свежей версии исходного кода в восходящем репозитории. Команда является одним из вариантов обновления заданий, другие методы описаны в разделе Upgrading Recipes [1].

Команда devtool upgrade позволяет гибко задавать выпуск исходного кода и схемы версий, извлекать код в workspace или в отдельный каталог и может работать с любыми формами исходного кода, поддерживаемыми сборщиками.

Процесс обновления показан на рисунке и описан ниже.

Инициирование обновления с помощью команды devtool upgrade требует наличия локального уровня вне workspace, а также наличия исходных кодов в каталоге, указанном переменной SRC_URI в задании (например, архив с новой версией в имени или другой выпуск восходящего репозитория Git). Для обновления задания служит команда devtool upgrade -V version recipe. По умолчанию команда извлекает исходный код в каталог sources внутри workspace. Для записи файлов в другой каталог следует использовать команду devtool upgrade -V version recipe srctree. Опция -V указывает новую версии, по умолчанию извлекается последняя версия.
Если исходные файлы, указанные SRC_URI, размещены в репозитории Git, нужно использовать опцию -S с указанием выпуска (revision) программы.

После того, как devtool найдет задание, используется переменная SRC_URI для нахождения исходного кода и всех изменений (patch) от других разработчиков. В результате команда организует исходный код, новую версию задания, а также файл дополнения в workspace.

При наличии локальных файлов, не являющихся исправлениями (файлы, указанные с file:// в переменной SRC_URI, за исключением *.patch и *.diff) эти файлы копируются в каталог oe-local-files созданного дерева исходного кода, где эти файлы можно редактировать. Внесенные в эти файлы изменения или добавления будут включены в следующую сборку вместе с другими изменениями исходного кода.
Устранение конфликтов, связанных с обновлением, которые могут возникать в результате несоответствия изменений в правках (patch), указанных SRC_URI, новым версиям программ. В таких случаях нужно редактировать файлы исходного кода и использовать процедуру git rebase для устранения конфликта. Все конфликты должны быть устранены до перехода к следующему этапу.
Сборка задания или повторная сборка образа выполняется с помощью команды devtool build recipe или devtool build-image image.
Развертывание результатов сборки после команды devtool build для проверки работоспособности на целевой системе или в эмуляторе QEMU. При развертывании образа предполагается наличие в этом образе SSH, а при использовании реального оборудования — доступ к платформе через сеть с хоста разработки. Для развертывания образа служит команда devtool deploy-target recipe target, где параметр target указывает целевую систему. Для переноса образа на физическую платформу потребуются дополнительные команды в зависимости от конкретного устройства.
Завершение работы с заданием по команде devtool finish recipe layer создает все нужные правки (patch) соответствующие фиксациям (commit) в локальном репозитории Git, переносит задание на постоянный уровень (layer) и настраивает задание для обычной сборки вместо использования workspace. Восстанавливаются также состояния стандартных уровней и дерева источников. При необходимости можно воспользоваться командой devtool reset для возврата к работе с заданием.

2.5. Инструмент `devtool add`

Команда devtool add автоматически создает задание на основе дерева исходных кодов, указанного в команде. В настоящее время команда способна работать с заданиями:

Autotools (autoconf и automake);
Cmake;
Scons;
qmake;
Makefile;
внешние модули ядра;
двоичные пакеты (опция -b);
модули Node.js;
модули Python, использующие setuptools или distutils.

За исключением двоичных пакетов, определение способа обработки исходных кодов выполняется автоматически на основе имеющихся в дереве кода файлов. Например, при обнаружении файла CMakeLists.txt предполагается использование CMake.

В большинстве случаев для правильной сборки нужно редактировать созданное автоматически задание. Для получения нужного результата может потребоваться несколько итераций. После сборки можно проверить задание на целевом устройстве.

2.5.1. Имя и версия

Если в команде не указано имя и версия, devtool add использует метаданные дерева источников в попытке определения имени и версии собираемой программы. На основе этих данных указывается имя и создается задание. Если имя и версию определить не удалось, выводится сообщение об ошибке. В таких случаях следует повторить команду с указанием хотя бы имени или версии. Иногда определение имени и версии из дерева кода может быть ошибочным. В таких случаях следует сбросить задание командой devtool reset -n recipename, а затем снова ввести devtool add с указанием имени и/или версии.

2.5.2. Нахождение и отображение зависимостей

Команда devtool add пытается найти зависимости при сборке и отображает их на другие задания в системе, внося их имена в переменную DEPENDS. Если зависимость не удается сопоставить, выводится сообщение об этом. Невозможность отобразить зависимость может быть связана с тем, что имя не распознано или недоступно. В последнем случае следует использовать команду devtool add для добавления задания, выполняющего зависимость и после этого обновить переменную DEPENDS в исходном задании, включив в нее новое задание.

Если нужно добавить зависимости при работе, это можно сделать в форме RDEPENDS_${PN} += «dependency1 dependency2 …«.

Команда devtool add зачастую не может различить обязательные и необязательные зависимости и некоторые найденные зависимости могут оказаться необязательными. В случае сомнений следует обратиться к документации или сценарию configure в программе собираемого задания. Иногда необязательную зависимость можно исключить параметром сценария configure.

2.5.3. Описание лицензии

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

Команда devtool add устанавливает значение переменной LIC_FILES_CHKSUM с указанием всех файлов, относящихся к лицензии. Следует помнить, что информация о лицензии часто указывается в комментариях в начале исходных файлов или документации и команда в таких случаях не находит эти данные. Поэтому может потребоваться изменение переменной LIC_FILES_CHKSUM для указания таких комментариев. Особенно важна установка LIC_FILES_CHKSUM для сторонних программ. Механизм контрольных сумм пытается обеспечить корректное указание лицензий при обновлении задания. Все изменения файлов с лицензиями обнаруживаются и выводится сообщение об ошибке с предложением проверить текст лицензии.

Если команда devtool add не может найти данных о лицензировании, в переменной LICENSE устанавливается значение CLOSED, а LIC_FILES_CHKSUM сбрасывается. Это позволяет продолжить разработку, хотя установки вряд ли будут корректны во всех случаях. Следует проверить документацию и файлы исходного кода собираемой программы для определения действующей лицензии.

2.5.4. Добавление программ на основе Makefile

Инструмент Make очень часто применяется в фирменных и открытых программах, но файлы Makefile зачастую не рассчитаны на кросс-компиляцию. Поэтому devtool часто не может обеспечить корректную сборку с такими файлами. Например, часто вызывается напрямую компилятор gcc вместо использования переменной CC. В среде кросс-компиляции gcc обычно является компилятором сборочного хоста, а кросс-компилятор называется иначе, например, arm-poky-linux-gnueabi-gcc и может требовать дополнительных аргументов (например, sysroot для целевой машины).

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

Возможно придется изменить Makefile для замены жестко заданных инструментов сборки (скажем, gcc и g++).
Среда для работы Make организуется с использованием различных стандартных переменных (например, CC, CXX и т. п.) аналогично организации среды сценарием настройки SDK. Простейшим способом увидеть эти переменные является ввод команды devtool build для задания и просмотр файла oe-logs/run.do_compile, в начале которого будет присутствовать список устанавливаемых переменных. Можно воспользоваться этими переменными в Makefile.
Если в Makefile принятое по умолчанию значение переменной установлено оператором =, оно переопределяет установленное в среде значение, что обычно нежелательно. В этом случае можно заменить в Makefile оператор на ?= или принудительно установить значение в команде make. Для принудительной установки значений в командной строке следует добавить значения в переменную задания EXTRA_OEMAKE или PACKAGECONFIG_CONFARGS. Например, EXTRA_OEMAKE += «‘CC=${CC}’ ‘CXX=${CXX}'». Здесь параметры даны в одинарных кавычках, поскольку значения могут включать пробелы.
Жесткое указание путей в Makefile зачастую создает проблемы при кросс-компиляции, поскольку эти пути обычно указывают каталоги хоста сборки, которые могут быть доступны лишь для чтения или приводить к «загрязнению» кросс-компиляции, поскольку относятся к хосту сборки, а не к целевой системе. Следует исправить Makefile, используя переменные с префиксом или иные переменные для решения проблемы.
Иногда Makefile использует относящиеся к цели команды, такие как ldconfig. В таких случаях можно применить правки, удаляющие ненужные команды из Makefile.

2.5.5. Добавление естественных инструментов

Часто требуется собрать дополнительные инструменты для работы на хосте сборки, а не в целевой системе. Следует указывать такие требования при запуске devtool add одним из указанных ниже способов.

Указать имя задания с суффиксом -native для сборки его лишь на сборочном хосте.
Указать опцию ‐‐also-native в команде devtool add command, создающую дополнительно файл задания -native.

Если нужно добавить инструмент, включенный в дерево кода, собираемого для цели, можно собрать компоненты для хоста сборки и цели раздельно, а не в одном процессе компиляции, например с помощью опции ‐‐also-native.

2.5.6. Добавление модулей Node.js

Команду devtool add можно применять для добавления модулей Node.js через npm, а также из удаленного или локального репозитория. Добавление через npm выполняется по команде вида devtool add «npm://registry.npmjs.org;name=forever;version=0.15.1». Параметры name и version являются обязательными. Создаются файлы блокировки и упаковки, которые указываются в задании для «замораживания» выбранной изначально версии в зависимостях. Сохраняются также контрольные суммы для проверки при последующих выборках. Это обеспечивает воспроизводимость и целостность задания.

URL нужно указывать в кавычках. Это не нужно devtool add, но оболочка считает символ ; разделителем команд, поэтому без кавычек devtool add не получит другие части и возникнет ошибка «command not found». Для поддержки добавления модулей Node.js в SDK нужно включить задание nodejs.

При добавлении модулей Node.js из локального или удаленного репозитория используется команда вида devtool add https://github.com/diversario/node-ssdp. В этом случае devtool извлечет файлы из репозитория Git, определит код Node.js, извлечет файлы с помощью npm и установит переменную SRC_URI.

2.6. Работа с заданиями

При сборке задания с помощью команды devtool build обычно выполняются перечисленные ниже действия.

Извлечение исходного кода.
Распаковка исходного кода.
Настройка конфигурации.
Компиляция.
Установка результатов сборки.
Упаковка установленных результатов (создание пакета).

Для заданий из рабочего пространства извлечение и распаковка исходного кода отключены, поскольку код уже подготовлен к использованию. Каждый из этапов сборки оформлен в виде функции (задачи), которая обычно имеет префикс do_ (например, do_fetch, do_unpack). Эти функции обычно являются сценариями оболочки, но могут быть написаны и на языке Python.

При просмотре содержимого задания можно увидеть, что оно не включает полных инструкций по сборке программ. Общая функциональность размещена в классах, наследуемых с помощью директивы inherit. Этот метод позволяет указывать в задании лишь специфические аспекты собираемой программы. Класс base неявно наследуется всеми заданиями и обеспечивает функциональность, требуемую для большинства заданий.

2.6.1. Поиск журнала и рабочих файлов

После первого вызова команды devtool build задания, созданные с помощью команды devtool add, чей исходный код был изменен командой devtool modify, содержат в дереве исходного кода символьные ссылки, указанные ниже.

oe-logs указывает каталог, где создаются журнальные файлы и сценарии запуска для каждого этапа сборки.
oe-workdir указывает временную рабочую область задания. В этой области важны несколько каталогов.

- image/ содержит все файлы, установленные задачей do_install. В задании этот каталог обозначен ${D}.
- sysroot-destdir/ содержит часть файлов, установленных задачей do_install, которые помещены в общий каталог sysroot (2.6.3. Совместное использование файлов заданиями).
- packages-split/ содержит каталоги для каждого пакета, созданного заданием (2.6.4. Подготовка пакетов).

Информация в этих каталогах поможет разобраться с каждым этапом сборки.

2.6.2. Установка параметров настройки

Если программы задания собираются с помощью GNU autoconf, программе передается фиксированный набор аргументов для включения кросс-компиляции и дополнений, заданных переменной EXTRA_OECONF или PACKAGECONFIG_CONFARGS в задании. Если нужно передать дополнительные параметры, их следует добавлять в переменную EXTRA_OECONF или PACKAGECONFIG_CONFARGS. В других поддерживаемых инструментах сборки применяются похожие переменные (например, EXTRA_OECMAKE для CMake, EXTRA_OESCONS для Scons и т. п.). Если нужно передать опции команде make, можно использовать переменную EXTRA_OEMAKE или PACKAGECONFIG_CONFARGS.

Для получения информации об установке упомянутых выше параметров можно воспользоваться командой devtool configure-help. Команда точно определяет передаваемые опции и показывает их вместе с другими аргументами, которые могут быть переданы через EXTRA_OECONF или PACKAGECONFIG_CONFARGS. Если это возможно, команда также покажет вывод сценария configure с опцией ‐‐help в качестве справки.

2.6.3. Совместное использование файлов заданиями

Задания часто используют файлы других заданий на хосте сборки. Например, приложению, связанному с общей библиотекой, нужно доступ к библиотеке и соответствующим заголовкам. Такой доступ обеспечивается в eSDK через sysroot. Каталог имеется для каждой «машины» поддерживаемой SDK. На практике это означает наличие sysroot для целевой машины и хоста сборки.

Заданиям никогда не следует записывать файлы напрямую в sysroot, а нужно устанавливать их с помощью задачи do_install в стандартные места внутри каталога ${D}. Часть этих файлов автоматически попадает в sysroot. Такое ограничение обусловлено тем, что практически все файлы sysroot указываются в манифестах, чтобы обеспечить возможность их удаления при изменении или удалении задания. Это позволяет исключать устаревшие файлы.

2.6.4. Подготовка пакетов

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

При выполнении задачи do_package файлы, установленные задачей do_install делятся на основной пакет, который почти всегда называется по имени задания, и несколько других пакетов. Это разделение обусловлено тем, что не все установленные файлы нужны в образе. Например, в рабочем образе может быть не нужна документация, для каждого задания файлы документации выделяются в пакет -doc. Задания для пакетов с необязательными модулями могут подвергаться дополнительному разделению.

После сборки задания можно посмотреть распределение файлов в каталоге oe-workdir/packages-split, где каждый пакет помещен в свой каталог. Распределение файлов определяется переменными PACKAGES и FILES за исключением некоторых сложных случаев. В переменной PACKAGES указаны все созданные пакеты, а FILES содержит распределение файлов по пакетам с использованием переопределений для указания пакетов. Например, FILES_${PN} указывает файлы основного пакета (который называется по имени задания ${PN}). Порядок значений в переменной PACKAGES важен и для каждого установленного файла первый пакет, значение для которого в FILES соответствует файлу, будет пакетов, куда включается файл. Для переменных PACKAGES и FILES имеются принятые по умолчанию значения, поэтому их установка в задании может оказаться ненужной, если задание применяет стандартное размещение файлов.

2.7. Восстановление исходного состояния целевого устройства

При использовании команды devtool deploy-target для записи вывода задания в целевую систему и работе с имеющимися компонентами системы может возникнуть потребность восстановить файлы, которые имелись до ввода команды devtool deploy-target. Эта команда создает копии перезаписываемых файлов и можно воспользоваться командой devtool undeploy-target для восстановления, например, devtool undeploy-target lighttpd root@192.168.7.2. При развертывании нескольких приложений можно отказаться от всех с помощью опции -a, например, devtool undeploy-target -a root@192.168.7.2.

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

Команды devtool deploy-target и devtool undeploy-target в настоящее время не взаимодействуют с системами управления пакетами на целевом устройстве (например, RPM или OPKG). Поэтому не следует смешивать на целевом устройстве операции менеджера пакетов и devtool deploy-target во избежание конфликтов.

2.8. Установка дополнительных элементов в eSDK

Пакет eSDK обычно распространяется с небольшим набором инструментов и библиотек. Минимальный вариант SDK является почти пустым и заполняется по мере необходимости. Иногда может явно требоваться установка дополнительных элементов в SDK. Такие элементы следует сначала найти с помощью команды devtool search. Предположим, например, что нужна привязка к libGL, но пакет с libGL не известен. Можно найти его по команде

     $ devtool search libGL
     mesa                  A free implementation of the OpenGL API

Узнав задание (mesa), его можно установить командой вида devtool sdk-install mesa. По умолчанию команда devtool sdk-install предполагает наличие собранного задания у поставщика SDK. Если элемент недоступен и его можно собрать из исходного кода, можно использовать опцию -s.

     $ devtool sdk-install -s mesa

Важно помнить, что сборка элемента занимает существенно больше времени, нежели установка собранного. Если задания для элемента нет, но нужно добавить элемент в SDK, сначала потребуется команда devtool add.

2.9. Обновление установленного eSDK

При работе с eSDK, который время от времени обновляется (сторонний SDK), может потребоваться установка обновлений SDK вручную. Для этого служит команда devtool sdk-update. Здесь предполагается, что у поставщика SDK имеется принятый по умолчанию идентификатор URL для обновления (SDK_UPDATE_URL), как указано в приложении B.4. Обновление eSDK после установки. При отсутствии такого URL, его нужно указать явно в виде devtool sdk-update path_to_update_directory, указывая URL опубликованного SDK, а не установщика, который был загружен ранее.

2.10. Создание SDK с дополнительными компонентами

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

Установка при необходимости eSDK в качестве базы для производного SDK.
Выполнение сценария организации среды для SDK.
Добавление библиотек и других компонент с помощью команды devtool add.
Выполнение команды devtool build-sdk.

На этих этапах принимаются задания, добавленные в workspace и создается новый установщик SDK, содержащий эти задания и соответствующие двоичные файлы. Задания переносятся в отдельный уровень производного SDK, оставляя каталог workspace чистым и готовым для работы с другими заданиями.

Глава 3. Использование стандартного SDK

В этой главе описана установка и использование стандартного SDK. Сравнение стандартных и расширяемых SDK приведено в разделе 1.1. Ведение. Стандартный SDK позволяет работать с проектами на основе Makefile и Autotools. Глава 4. Использование инструментов SDK содержит более подробные сведения.

3.1. Что такое стандартный SDK?

Стандартный SDK включает инструменты и библиотеки для кросс-разработки, адаптированные под конкретный образ. Стандартный SDK является более традиционным средством разработки, нежели eSDK, с дополнительным инструментом devtool. Установленный SDK включает множество файлов и каталогов, а также сценарий организации среды, конфигурационные файлы, корневые файловые системы для хоста и цели. Структура каталогов описана в приложении A.4. Структура каталогов стандартного SDK.

3.2. Установка SDK

Первым делом нужно установить SDK на хосте сборки с помощью установочного сценария *.sh. Можно загрузить архив установщика, включающий собранные инструменты и файлы поддержки, из подходящего каталога toolchain в Index of Releases. Инструменты доступны для 32- и 64-битовой архитектуры. Инструментарий YP основан на образе core-image-sato или core-image-minimal и включает нужные для разработки библиотеки.

Имена архивов установщиков начинаются с представления хост-системы, за которой указывается целевая архитектура. Например, poky-glibc-host_system—image_type—arch-toolchain-release_version.sh, где строка host_system указывает систему разработки (i686 или x86_64), image_type указывает образ, для которого будет собран SDK (core-image-sato или core-image-minimal), arch задает целевую архитектуру (aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400 или cortexa8hf-neon), release_version — номер выпуска YP (3.0, 3.0+snapshot). Например, установщик для 64-битовой хост-системы и целевой архитектуры i586-tuned на основе образа core-image-sato и текущего выпуска 3.0 будет называться poky-glibc-x86_64-core-image-sato-i586-toolchain-3.0.sh.

Другим вариантом является самостоятельная сборка SDK, как описано в приложении A.2. Сборка установщика SDK.

SDK и инструменты самодостаточны ии устанавливаются в каталог poky_sdk внутри домашнего каталога, хотя можно выбрать иное место для установки. Однако местоположение SDK должна быть доступно для записи всем пользователям SDK. Ниже приведена команда для запуска установщика на 64-битовой системе x86 для 64-битовой архитектуры x86 с установкой SDK в каталог ~/Downloads/. Если у вас нет полномочий записи в каталог установки SDK, программа сообщит об этом и завершит работу.

     $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-3.0.sh
     Poky (Yocto Project Reference Distro) SDK installer version 3.0
     ===============================================================
     Enter target directory for SDK (default: /opt/poky/3.0):
     You are about to install the SDK to "/opt/poky/3.0". Proceed [Y/n]? Y
     Extracting SDK........................................ ..............................done
     Setting it up...done
     SDK has been successfully set up and is ready to be used.
     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
      $ . /opt/poky/3.0/environment-setup-i586-poky-linux

В приложении A.4. Структура каталогов стандартного SDK описаны каталоги установленного SDK.

3.3. Запуск сценария настройки среды SDK

После установки SDK нужно запустить сценарий организации среды SDK, чтобы можно было начать работу. Сценарий размещается в каталоге, указанном при установке SDK (по умолчанию /opt/poky/3.0). Перед запуском сценария следует проверить его соответствие архитектуре, для которой планируется разработка. Имена сценариев организации среды начинаются с environment-setup и включают целевую архитектуру. Ниже приведен пример запуска сценария для целевой машины IA с архитектурой i586.

     $ source /opt/poky/3.0/environment-setup-i586-poky-linux

При запуске сценария установки задаются те же переменные окружения, что и для eSDK, описанные в разделе 2.3. Запуск сценария организации среды eSDK.

Глава 4. Использование инструментов SDK

Инструменты SDK можно применять напрямую в проектах на основе Makefile и Autotools.

4.1. Проекты на основе Autotools

После установки подходящих инструментов кросс-разработки можно начать работу на основе процесса GNU Autotools, не входящего в систему сборки OE. Этапы процесс показаны на рисунке, дополнительную информацию можно найти на сайте GNOME Developer.

Ниже приведен пример разработки на основе Autotools простого проекта Hello World.

Создание и наполнение рабочего каталога.
```
     $ mkdir $HOME/helloworld
     $ cd $HOME/helloworld
```
В рабочем каталоге нужно создать файл с исходным кодом проекта, файл для подготовки конфигурации, а также файл для создания Makefile и файл README — hello.c, configure.ac, Makefile.am, README.

Для создания файла README, требуемого GNU Coding Standards, служит команда touch README. Остальные файлы проекта показаны ниже.
- hello.c
```
     #include <stdio.h>

     main()
        {
           printf("Hello World!\n");
        }      
```
- configure.ac
```
     AC_INIT(hello,0.1)
     AM_INIT_AUTOMAKE([foreign])
     AC_PROG_CC
     AC_CONFIG_FILES(Makefile)
     AC_OUTPUT
```
- Makefile.am
```
     bin_PROGRAMS = hello
     hello_SOURCES = hello.c
```
Выполнение сценария организации среды кросс-разработки из каталога SDK. Имя сценария начинается с environment-setup и включает архитектуру машины, а затем строку poky-linux. Например, сценарий из принятой по умолчанию установки SDK для 32-битовой архитектуры Intel x86 и выпуска Zeus YP запускается командой source /opt/poky/3.0/environment-setup-i586-poky-linux.
Создание сценария configure с помощью команды autoreconf, которая запустит нужные инструменты Autotools, такие как aclocal, autoconf, automake. Если при работе autoreconf возникнут ошибки, связанные с configure.ac и указывающие отсутствие файлов, можно использовать опцию -i для копирования нужных файлов.
Кросс-компиляция проекта с использованием кросс-компилятора. Переменная окружения CONFIGURE_FLAGS задает минимальные аргументы для GNU configure
```
     $ ./configure ${CONFIGURE_FLAGS}
```
Для проектов на основе Autotools можно использовать инструменты кросс-разработки, просто передав подходящую опцию host сценарию configure. Используемая опция host выводится из имени сценария организации среды в каталоге, куда установлены кросс-инструменты. Например, опция host для целевой платформы ARM, использующей GNU EABI, будет иметь значение armv5te-poky-linux-gnueabi (имя сценария environment-setup-armv5te-poky-linux-gnueabi). Приведенная ниже команда обновит проект и настроит его для сборки с помощью подходящих кросс-инструментов.
```
$ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
```
Сборка и установка проекта с помощью приведенных ниже команд с указанием целевого каталога.
```
     $ make
     $ make install DESTDIR=./tmp
```
Переменные окружения, используемые сценарием организации среды кросс-разработки и их переопределение в Makefile описаны в разделе 4.2. Задания на основе Makefile.

Следующая команда обеспечивает простой способ проверить инсталляцию проекта, выводя архитектуру, где может работать двоичный файл (должна совпадать с архитектурой, поддерживаемой кросс-инструментами).
```
     $ file ./tmp/usr/local/bin/hello
```
Выполнение программы на целевом оборудовании. Если целевым устройством является хост сборки, можно просто ввести команду ./tmp/usr/local/bin/hello, в результате чего на консоли появится сообщение «Hello World!».

4.2. Задания на основе Makefile

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

Здесь представлен простой процесс разработки на основе Makefile с описанием использования переменных окружения и переменных Makefile.

Основной целью является рассмотрение 3 разных вариантов поведения переменных.

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

Независимо от способа установки переменных опция make -e отдает преимущество настройкам сценария организации среды SDK.

$ make -e target

В новой оболочке переменные для SDK не устанавливаются, пока не будет запущен сценарий организации среды, например, команда echo ${CC} выведет пустую (null) строку значения переменной для компилятора (CC).

Сценарий организации среды SDK для 64-битового хоста сборки и целевой архитектуры i586-tuned с образом core-image-sato, использующим выпуск YP 3.0, запускается приведенной ниже командой.

     $ source /opt/poky/3.0/environment-setup-i586-poky-linux
     $ echo ${CC}
     i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux

Для иллюстрации снова рассмотрим простой пример Hello World!

Создание и наполнение рабочего каталога.

     $ mkdir $HOME/helloworld
     $ cd $HOME/helloworld

В рабочем каталоге нужно создать файл main.c, где вызывается функция, module.h с заголовками и module.c с определением функции, как показано ниже.

main.c

     #include "module.h"
     void sample_func();
     int main()
     {
        sample_func();
        return 0;
     }

module.h

     #include <stdio.h>
     void sample_func();

module.c

     #include "module.h"
     void sample_func()
     {
             printf("Hello World!");
             printf("\n");
     }

Выполнение сценария организации среды кросс-разработки из каталога SDK. Имя сценария начинается с environment-setup и включает архитектуру машины, а затем строку poky-linux. Например, сценарий из принятой по умолчанию установки SDK для 32-битовой архитектуры Intel x86 и выпуска Zeus YP запускается командой source /opt/poky/3.0/environment-setup-i586-poky-linux.
```
     $ source /opt/poky/3.0/environment-setup-i586-poky-linux
```

Создание Makefile. В этом примере Makefile включает 2 строки, используемые для установки переменной CC. Одна строка идентична устанавливаемой сценарием организации среды SDK, а другая устанавливает в CC значение «gcc» (принятый по умолчанию компилятор GNU на хосте сборки).

     # CC=i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
     # CC="gcc"
     all: main.o module.o
         ${CC} main.o module.o -o target_bin
     main.o: main.c module.h
             ${CC} -I . -c main.c
     module.o: module.c module.h
             ${CC} -I . -c module.c
     clean:
             rm -rf *.o
             rm target_bin

Сборка проекта с помощью команды make для создания выходного двоичного файла. Поскольку переменные в Makefile закомментированы, применяться будет значение CC, заданное сценарием организации среды SDK.

$ make
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin

Из приведенного вывода видно, что применялся компилятор, заданный значением CC в сценарии установки. Можно переопределить переменную CC, установив тоже значение путем удаления символа комментария из Makefile и повторного запуска make.

     $ make clean
     rm -rf *.o
     rm target_bin
     #
     # Edit the Makefile by uncommenting the line that sets CC to "gcc"
     #
     $ make
     gcc -I . -c main.c
     gcc -I . -c module.c
     gcc main.o module.o -o target_bin

Здесь не использовался кросс-компилятор.

Следующий пример показывает переопределение переменной в команде (символы комментариев в Makefile восстановлены).

$ make clean
rm -rf *.o
rm target_bin
#
# Edit the Makefile to comment out the line setting CC to "gcc"
#
$ make
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
$ make clean
rm -rf *.o
rm target_bin
$ make CC="gcc"
gcc -I . -c main.c
gcc -I . -c module.c
gcc main.o module.o -o target_bin

Во втором случае команда задавала использование компилятора, переопределяющее установку SDK.

Последний пример использует установку в Makefile переменной «gcc», но применяется опция «-e» в команде make.

$ make clean
rm -rf *.o
rm target_bin
#
# Edit the Makefile to use "gcc"
#
$ make
gcc -I . -c main.c
gcc -I . -c module.c
gcc main.o module.o -o target_bin
$ make clean
rm -rf *.o
rm target_bin
$ make -e
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin

В результате указания опции -e применяются настройки SDK, независимо от Makefile.

Выполнение программы.
```
     $ ./target_bin
     Hello World!
```
При использовании кросс-компилятора для сборки target_bin под иную архитектуру, файл нужно запускать на соответствующем устройстве.

Приложение A. Получение SDK

A.1. Собранные установщики

Можно использовать имеющиеся собранные установщики, найдя и запустив соответствующий сценарий инсталляции SDK из состава YP. Таким способом можно выбрать и загрузить SDK для нужной архитектуры, а затем запустить сценарий для установки вручную, как описано ниже.

Загрузка страницы установщиков http://downloads.yoctoproject.org/releases/yocto/yocto-3.0/toolchain/
Выбор каталога для хоста сборки (например, i686 для 32-битовой машины или x86_64 для 64-битовой).
Выбор и загрузка установщика SDK с учетом хоста сборки, целевой системы и типа образа. Имена сценариев установки имеют форму poky-glibc-host_system-core-image-type—arch-toolchain[-ext]-release.sh, где host_system представляет хост разработки (i686 или x86_64), type указывает образ (sato или minimal), arch — архитектуру (aarch64, armv5e, core2-64, coretexa8hf-neon, i586, mips32r2, mips64 или ppc7400, а release — выпуск YP. Установщики для стандартных SDK не имеют суффикса -ext.

Инструменты YP основаны на образе core-image-sato или core-image-minimal и включают двоичные файлы, подходящие для этих образов. Например, для 64-битового хоста сборки x86 и 64-битовой целевой системы core2 следует перейти в каталог x86_64 и загрузить файл (для расширенного SDK) poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-3.0.sh.
Запуск установщика. Например, для запуска из каталога Downloads в домашнем каталоге служит команда ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-3.0.sh. При выполнении сценария указывается каталог для инструментов. Структура каталогов показана в приложениях A.4. Структура каталогов стандартного SDK и A.5. Структура каталогов eSDK.

A.2. Сборка установщика SDK

Другим решением служит самостоятельная сборка установщика SDK, этапы которой описаны ниже.

Организация среды сборки BitBake и прочтите раздел Preparing the Build Host [1], где описана подготовка хоста сборки на машине Linux или машине с CROPS.
Клонирование репозитория poky в локальный каталог исходных кодов (локальный репозиторий poky) в соответствии с разделами Cloning the poky Repository, а также Checking Out by Branch in Poky и Checking Out by Tag in Poky [1], выбрав нужную ветвь.
Инициализация среды сборки путем запуска из корневого каталога дерева источников (poky) сценария организации среды oe-init-build-env для настройки окружения системы сборки OE на сборочном хосте.
```
     $ source oe-init-build-env
```
Этот сценарий создаст каталог сборки (по умолчанию build) внутри каталога источников, а также сделает этот каталог текущим.
Проверка корректности выбора машины. Переменная MACHINE в файле local.conf внутри каталога сборки должна соответствовать архитектуре, для которой будет выполняться сборка.
Проверка корректности выбора машины для SDK. При сборке инструментов для архитектуры, отличающейся от архитектуры хоста сборки следует убедиться, что переменная SDKMACHINE в файле local.conf сборочного каталога установлена корректно. При сборке установщика eSDK переменная SDKMACHINE должна указывать архитектуру машины, применяемой для сборки установщика. Некорректная установка SDKMACHINE ведет к отказу сборки с выводом сообщения, подобного приведенному ниже.
```
The extensible SDK can currently only be built for the same 
architecture as the machine being built on - SDK_ARCH is set 
to i686 (likely via setting SDKMACHINE) which is different from 
the architecture of the build machine (x86_64). Unable to continue.
```
Сборка установщика SDK. Для сборки и создания образа стандартного SDK служит команда вида bitbake image -c populate_sdk, для расширенного — bitbake image -c populate_sdk_ext (параметр image должен указывать используемый образ, например, core-image-sato). По завершении работы bitbake установщик будет находиться в каталоге tmp/deploy/sdk внутри каталога сборки.

По умолчанию приведенные выше команды BitBake не создают статических двоичных файлов. Если планируется использование инструментов для сборки статических библиотек, нужно убедиться в наличии в SDK соответствующих библиотек разработки. Переменная TOOLCHAIN_TARGET_TASK в файле local.conf должна быть установлена до сборки установщика SDK и иметь вид TOOLCHAIN_TARGET_TASK_append = » libc-staticdev».
Запуск установщика из каталога tmp/deploy/sdk в сборочном каталоге. Например,
```
     $ cd ~/poky/build/tmp/deploy/sdk
     $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-3.0.sh
```
При выполнении сценария нужно будет указать каталог установки. Структура каталогов описана в приложениях A.4. Структура каталогов стандартного SDK и A.5. Структура каталогов eSDK.

A.3. Извлечение корневой файловой системы

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

загрузка образа с использованием NFS;
использование корневой файловой системы в качестве целевой sysroot;
разработка целевых приложений, использующих корневую файловую систему в качестве целевой sysroot.

Этапы извлечения корневой файловой системы описаны ниже.

Нахождение и загрузка архива подготовленного образа корневой файловой системы. Файлы таких образов доступны на странице Index of Releases в каталоге machines. Образы представлены в архивах *.tar.bz2 для поддерживаемых машин, а также образы *.ext4 для использования с QEMU. Имена файлов с образами имеют форму core-image-profile—arch.tar.bz2, где profile указывает профиль образа файловой системы (lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs, sato, sato-dev, sato-sdk, sato-sdk-ptest). Описания образов приведены в разделе Images. Строка arch в имени файла указывает целевую архитектуру (beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb, genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb, mpc8315e-rdb, mpc8315e-rdb-lsb, qemu*). Корневые файловые системы в составе YP основаны на образах core-image-sato и core-image-minimal.

Например, для целевого устройства BeagleBone и образа core-image-sato-sdk следует выбрать файл core-image-sato-sdk-beaglebone-yocto.tar.bz2.
Инициализация среды кросс-разработки с помощью команды source для сценария настройки среды. Сценарий размещается в каталоге установки инструментов (например, poky_sdk). Ниже приведен пример запуска сценария для установки, описанной в приложении A.1. Собранные установщики
```
     $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
```
Извлечение корневой файловой системы с помощью команды runqemu-extract-sdk. Например, для извлечения корневой файловой системы из образа, загруженного со страницы Index of Releases, в каталог core2-64-sato служит команда runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato. После этого можно указать beablebone-sato в качестве целевой sysroot.

A.4. Структура каталогов стандартного SDK

На рисунке показана структура каталогов стандартного SDK, создаваемая установочным сценарием *.sh. Установленный SDK включает сценарий настройки среды, файл конфигурации для цели и корневую файловую систему для разработки объектов, предназначенных для целевой платформы.

Наклонный шрифт на рисунке показывает заменяемые части имен файлов и каталогов. Например, install_dir/version является каталогом установки SDK, который по умолчанию называется /opt/poky/, а version представляет конкретный выпуск SDK (например, 3.0). Кроме того, target представляет целевую архитектуру (например, i586), а host — архитектуру системы разработки (например, x86_64). Таким образом, полные имена каталогов в sysroots могут быть i586-poky-linux (цель) и x86_64-pokysdk-linux (хост).

A.5. Структура каталогов eSDK

На рисунке показана структура каталогов eSDK, создаваемая установочным сценарием *.sh.

Структура каталогов eSDK отличается от структуры стандартного SDK отсутствием отдельных частей для хоста и цели, поскольку здесь они не разделяются. Расширяемый SDK содержит встроенную копию системы сборки OE со своими sysroot.

В структуре каталогов следует отметить сценарий организации среды для SDK, файл конфигурации для цели и журнальные файлы (log) для сценария подготовки системы сборки OE, запускаемого установщиком и BitBake.

Наклонный шрифт на рисунке показывает заменяемые части имен файлов и каталогов. Например, install_dir/version является каталогом установки SDK, который по умолчанию называется poky_sdk, а target представляет целевую архитектуру (например, i586).

Приложение B. Настройка eSDK

B.1. Конфигурация eSDK

Основной частью расширяемого SDK является настроенная копия системы сборки OE, из которой пакет был создан. Конфигурация SDK выводится с использованием системы сборки и приведенных ниже фильтров, которые система сборки OE применяет к файлам local.conf и auto.conf.

Переменные, начинающиеся с /, исключаются в предположении, что это пути, зависящие от хоста сборки.
Переменные из SDK_LOCAL_CONF_BLACKLIST исключаются, поскольку их не разрешено передавать из системы сборки OE в конфигурацию eSDK. Обычно эти переменные специфичны для машины, где работает система сборки и могут вызывать проблемы в конфигурации eSDK. Список переменных, исключаемых по умолчанию, приведен в описании переменной SDK_LOCAL_CONF_BLACKLIST [2].
Переменные из SDK_LOCAL_CONF_WHITELIST включаются и могут переопределять предшествующие фильтры. По умолчанию список пуст.
Глобально наследуемые классы с INHERIT из переменной SDK_INHERIT_BLACKLIST отключаются. Это стандартный метод исключения классов, которые могут создавать проблемы или не нужны в контексте SDK. По умолчанию список включает классы buildhistory и icecc.

Кроме того, при наличии файла conf/sdk-extra.conf его содержимое добавляется в конце conf/local.conf создаваемого SDK без фильтрации. Файл sdk-extra.conf полезен в тех случаях, когда нужно установить переменную для SDK, но не для системы сборки OE, используемой для создания SDK.

B.2. Настройка eSDK для хоста сборки

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

Если конфигурация SDK наследует дополнительные классы через переменную INHERIT и эти классы не следует включать в SDK, их можно отключить через переменную SDK_INHERIT_BLACKLIST, как описано в предыдущем параграфе. По умолчанию SDK_INHERIT_BLACKLIST устанавливается с помощью оператора ?=, поэтому нужно определить весь список с использованием = или добавлять значения с помощью _append или оператора +=. Описания операторов приведены в разделе Basic Syntax [3].
При наличии классов или заданий, добавляющих задачи в стандартный поток сборки (задачи, выполняемые как сборка заданий, а не вызываемые явно), нужно выполнить одно из указанных действий:
- после проверки принадлежности задачи к общему состоянию (т. е. их вывод сохраняется и может быть восстановлен из общего состояния) или ее способности быстро создаваться из задачи с общим состоянием имя задачи добавляется в SDK_RECRDEP_TASKS;
- отключаются все задачи, добавленные классом, если функциональность класса не нужна в eSDK; для отключения задач класс указывается в переменной SDK_INHERIT_BLACKLIST, как описано выше.
Как правило настраивается зеркало общего состояния, чтобы пользователи SDK могли добавлять элементы после установки SDK без сборки их из исходного кода (B.6. Дополнительные компоненты eSDK).
Для упрощения процедуры обновления SDK следует установить переменную SDK_UPDATE_URL (B.4. Обновление eSDK после установки.
При корректировке списка файлов и каталогов в переменной COREBASE (сверх уровней, добавленных в bblayers.conf) нужно указать эти файлы в переменной COREBASE_FILES для их копирования в SDK.
При использовании системой сборки OE своего сценария настройки окружения (не oe-init-build-env) нужно указать этот сценарий в переменной OE_INIT_ENV_SCRIPT. Это изменение нужно также отразить в переменной COREBASE_FILES, как описано выше.

B.3. Изменение названия установщика eSDK

Можно установить отображаемое имя установщика SDK с помощью переменной SDK_TITLE и пересборки установщика (A.2. Сборка установщика SDK). По умолчанию заголовок берется из DISTRO_NAME, а при отсутствии этой переменной — из DISTRO. Класс populate_sdk_base определяет принятое по умолчанию значение в форме SDK_TITLE ??= «${@d.getVar(‘DISTRO_NAME’) or d.getVar(‘DISTRO’)} SDK».

Существуют разные способы изменения этой переменной, но лучше установить ее в файле конфигурации дистрибутива. Это задает имя установщика SDK в рамках дистрибутива. Предположим, например, наличие уровня meta-mydistro и использование в нем иерархии файлов как в дистрибутиве poky. В этом случае можно обновить переменную SDK_TITLE в файле ~/meta-mydistro/conf/distro/mydistro.conf, используя форму SDK_TITLE = «your_title«.

B.4. Обновление eSDK после установки

При изменении конфигурации или метаданных для учета этих изменений в установленном SDK нужно выполнить дополнительные действия. Это позволит любому пользователю установленного SDK обновить пакет с помощью команды devtool sdk-update.

Создается каталог, доступный по протоколу HTTP или HTTPS (например, с помощью сервера Apache или Nginx) и содержащий опубликованный SDK.
Устанавливается переменная SDK_UPDATE_URL с указанием соответствующего HTTP или HTTPS URL. Установка переменной ведет к тому, что любой SDK собранный по умолчанию с этим URL, будет передавать идентификатор команде devtool sdk-update, как описано в разделе 2.9. Обновление установленного eSDK.
Обычным способом собирается eSDK (bitbake -c populate_sdk_ext imagename).
SDK публикуется с помощью команды oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory. Этот этап нужно повторять при каждом изменении SDK, которое следует делать доступным.

Выполнение этих действий позволит обновлять установленные SDK с помощью команды devtool sdk-update для получения и применения изменений, как описано в разделе 2.9. Обновление установленного eSDK.

B.5. Изменение каталога установки eSDK

При сборке установщика eSDK каталог установки по умолчанию определяется переменными DISTRO и SDKEXTPATH из класса populate_sdk_base в форме SDKEXTPATH ??= «~/${@d.getVar(‘DISTRO’)}_sdk». Этот каталог можно изменить через переменную SDKEXTPATH.

Существуют разные способы изменения этой переменной, но лучше установить ее в файле конфигурации дистрибутива. Это задает имя установщика SDK в рамках дистрибутива. Предположим, например, наличие уровня meta-mydistro и использование в нем иерархии файлов как в дистрибутиве poky. В этом случае можно обновить переменную SDKEXTPATH в файле ~/meta-mydistro/conf/distro/mydistro.conf, используя форму SDKEXTPATH = «some_path_for_your_installed_sdk«.

При запуске собранного установщика пользователю предлагается принять каталог some_path_for_your_installed_sdk для установки eSDK или указать свой каталог.

B.6. Дополнительные компоненты eSDK

Чтобы пользователи собранного eSDK могли добавлять элементы без их сборки из исходного кода, нужно выполнить ряд действий.

Проверка наличия требуемых для установки элементов:
- явная сборка элементов с использованием одного или нескольких метазаданий;
- сборка цели world с установкой EXCLUDE_FROM_WORLD_pn-recipename для ненужных заданий (см. описание EXCLUDE_FROM_WORLD).
Раскрытие каталога sstate-cache, создаваемого сборкой (обычно через сервер Apache или Nginx).
Установка конфигурации, позволяющей созданному SDK узнать свои настройки, для чего нужно задать переменную SSTATE_MIRRORS = «file://.* http://example.com/some_path/sstate-cache/PATH».
- Если указанное зеркало подходит как для системы сборки OE, использованной для создания SDK, так и для самого SDK (т. е. зеркало доступно обоим или при быстром выходе из строя на стороне системы сборки OE содержимое не будет препятствовать сборке), можно установить переменную в файле local.conf или файле конфигурации дистрибутива. Затем переменную можно включить в «белый список» SDK в форме SDK_LOCAL_CONF_WHITELIST = «SSTATE_MIRRORS».
- Дополнительно можно установить переменную SSTATE_MIRRORS только для SDK, создав файл conf/sdk-extra.conf в каталоге сборки или на любом уровне и поместив туда SSTATE_MIRRORS.
Второй вариант является наиболее безопасным для установки SSTATE_MIRRORS.

B.7. Минимизация размера установщика eSDK

По умолчанию eSDK включает элементы общего состояния для всего, что нужно при восстановлении образа, для которого собран SDK. Такая сборка ведет к размеру SDK, превышающему 1 Гбайт. Если это вызывает проблемы, можно собрать SDK, которого достаточно для установки и есть доступ к команде devtool, путем задания SDK_EXT_TYPE = «minimal». Это приведет к снижению размера SDK примерно до 35 Мбайт, что существенно ускорит загрузку и установку. Однако следует помнить, что этот вариант не установит библиотеки и инструменты, которые придется устанавливать «на лету» с помощью devtool или явной команды devtool
sdk-install.

В большинстве случаев при создании минимального SDK нужно включать также информацию о спектре пакетов, создаваемых системой. Это особенно важно, поскольку команда devtool add может эффективно сопоставлять зависимости в дереве источников с заданиями. Кроме того, это позволяет команде devtool search возвращать полезные результаты. Для упрощения задачи следует установить SDK_INCLUDE_PKGDATA = «1» (см. SDK_INCLUDE_PKGDATA).

Установка переменной SDK_INCLUDE_PKGDATA ведет к тому, что цель world собирается так, чтобы предоставить информацию обо всех доступных заданиях. Это существенно увеличивает время сборки и повышает размер SDK на 30-80 Мбайт в зависимости от числа включенных в конфигурацию заданий.

Можно использовать переопределение EXCLUDE_FROM_WORLD_pn-recipename для исключения ненужных заданий, однако считается, что нужно собрать цель world для предоставления дополнительных элементов SDK. Поэтому сборка world не должна вызывать неприемлемых издержек в большинстве случаев.

При установке SDK_EXT_TYPE = «minimal» предоставление зеркала общего состояния является обязательным, чтобы элементы можно было устанавливать по мере необходимости (см. B.6. Дополнительные компоненты eSDK).

Можно явно управлять включением инструментов при сборке SDK через установку SDK_INCLUDE_TOOLCHAIN = «1». в частности, полезно включать инструменты при установке SDK_EXT_TYPE = «minimal», где они исключены по умолчанию. Полезно также включать инструменты при создании небольших SDK для использования с IDE или иными средствами, где нужно избежать дополнительных шагов по установке инструментария.

Приложение C. Настройка стандартного SDK

C.1. Добавление пакетов

При сборке стандартного SDK по команде bitbake -c populate_sdk в SDK включается принятый по умолчанию набор пакетов, которым управляют переменные TOOLCHAIN_HOST_TASK и TOOLCHAIN_TARGET_TASK. Для включения дополнительных пакетов в инструментарий хоста служит переменная TOOLCHAIN_HOST_TASK, а для целевой платформы — TOOLCHAIN_TARGET_TASK.

C.2. Добавление документации API

Можно включить документацию API, а также другую документацию из заданий в стандартном SDK путем добавления api-documentation в переменную DISTRO_FEATURES, как показано ниже.

     DISTRO_FEATURES_append = " api-documentation"

Установка переменной заставит систему сборки OE подготовить документацию и включит ее в стандартный SDK.

Литература

[1] Yocto Project Development Tasks Manual, https://www.yoctoproject.org/docs/3.0/dev-manual/dev-manual.html.

[2] Yocto Project Reference Manual, https://www.yoctoproject.org/docs/3.0/ref-manual/ref-manual.html.

[3] BitBake User Manual, https://www.yoctoproject.org/docs/3.0/bitbake-user-manual/bitbake-user-manual.html.

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Software Development Kit — пакет для разработки приложений.

2Application Development Toolkit — инструменты для разработки приложений.

3Quick EMUlator.

4eSDK содержит инструменты и отладчик, если SDK_EXT_TYPE = «full» или SDK_INCLUDE_TOOLCHAIN = «1».

5Управление sysroot осуществляется с помощью devtool,что снижает вероятность повреждений при добавлении библиотек.

6Управление пакетами при работе можно добавить в стандартный SDK (по умолчанию его нет).

7Нужно собрать и сделать доступным общее состояние для устанавливаемых пакетов.

Рубрика: Linux | Комментарии отключены

Обзор и концепции Yocto Project

Опубликовано 14.12.2019 автором Nikolai Malykh

Yocto Project Overview and Concepts Manual

PDF

Scott Rifenbark

Scotty’s Documentation Services, INC

<srifenbark@gmail.com>

Этот документ основан на переводе Yocto Project Overview and Concepts Manual для выпуска 3.0 Yocto Project. Свежие версии оригинальных документов можно найти на странице документации Yocto Project. Размещенные там материалы более актуальны, нежели включенные в архивы пакета Yocto Project.

Глава 1. Обзор и концепции Yocto Project

1.1. Введение

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

Глава 2. Введение в YP содержит вводные сведения о YP, описание возможностей и сложностей YP, модели уровней, компонент и инструментов, методов разработки, эталонного дистрибутива Poky, системы сборки OpenEmbedded (OE) и некоторых базовых терминов Yocto.
Глава 3. Среда разработки YP поможет обрести понимание процессов разработки в YP. Здесь приведена информация о программах с открытым кодом, хосте для разработки, репозиториях исходных кодов YP, процессах работы с Git и YP, пример Git и сведения о лицензировании.
Глава 4. Концепции YP описывает связанные с YP концепции и поможет найти информацию о компонентах, разработке, кросс-инструментах и т. п.

Для более глубокого ознакомления следует обратиться к дополнительным источникам, перечисленным ниже.

Пошаговые инструкции для задач разработки содержатся в других документах YP. В руководстве для разработчиков [1] приведены примеры решения различных задач разработки. Руководство для разработчиков SDK [2] содержит подробные сведения об установке SDK, используемых при разработке приложений.
Справочные руководства включают справочник по YP [3] и справочник по разработке BSP¹ [4].

1.2. Дополнительная информация

Этот документ содержит базовую информацию по разным темам, поэтому для лучшего понимания будет полезно обратиться к дополнительным источникам. Сведения от YP можно получить на сайте Yocto Project. Краткая информация по сборке образов без углубления в YP приведена в документе [5]. В разделе Links and Related Documentation [3] приведены ссылки на дополнительные документы.

Глава 2. Введение в YP

2.1. Что такое YP

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

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

Дополнительная вводная информация приведена в статье и коротком видеоролике.

2.1.1. Возможности

Широкое распространение в отрасли. Многие производители микросхем, операционных систем, программ и поставщики услуг приспособили свою продукцию и услуги к использованию YP. Сообщество и компании, вовлеченные в YP, представлены на вкладках COMMUNITY и ECOSYSTEM сайта Yocto Project.
Независимость от архитектуры. YP поддерживает архитектуру Intel, ARM, MIPS, AMD, PPC и др. Большинство ODM, OSV и производителей микросхем создали и поддерживают пакеты BSP для своего оборудования. При использовании своих микросхем можно создать специальные пакеты BSP. Кроме того, YP поддерживает эмуляцию множества устройств на основе QEMU².
Простота переноса образов и кода. Вывод YP легко перенести из одной архитектуры в другую без смены среды разработки. Кроме того, если вы не можете обеспечить поддержку созданных образов или приложений, ее можно передать на поддержку коммерческим производителям Linux, таким как Wind River, Mentor Graphics, Timesys, ENEA.
Гибкость. Компании применяют YP множеством разных способов. Например, некоторые создают свои дистрибутивы Linux в качестве базы кода для разной продукции. Возможности настройки и поддержка уровней может упростить создание базового дистрибутива Linux подходящего для разных сфер применения.
Работа на устройствах с ограниченными ресурсами. В отличие от полных дистрибутивов Linux в YP можно создать дистрибутив, содержащий лишь требуемые встраиваемому устройству компоненты. Можно ограничиться функциями и пакетами, без которых устройство не сможет работать, а все остальное исключить. Для устройств с мониторами можно использовать системные компоненты X11, GTK+, Qt, Clutter, SDL и др., обеспечивающий широкий набор функций. Для простых устройств без монитора можно выбрать простой пользовательский интерфейс без мало нужных компонент.
Полнофункциональный инструментарий. Инструментарий для поддерживаемых архитектур подойдет для большинства случаев. Однако, если ваше оборудование поддерживает возможности, не доступные стандартным инструментам, это можно легко исправить, настроив инструментарий через параметры, зависящие от платформы. Если же требуется использовать сторонние инструменты, механизмы YP позволят сделать это.
Правила механизма взамен политики. Сосредоточение внимания на механизмах, а не политике обеспечивает свободу выбора правил на основе потребностей вместо приспособления к решениям того или иного поставщика программ.
Использование уровней. Многоуровневая инфраструктура YP группирует связанные между собой функции в отдельные наборы (уровни). Такой уровень можно при необходимости добавить непосредственно в проект. Использование уровней для разделения и группировки функций снижает уровень сложности и избыточности, позволяя без большого труда расширять систему и должны образом организовать функциональность.
Поддержка частичной сборки. При необходимости можно собирать и перестраивать отдельные пакеты. YP обеспечивает это с помощью схемы кэширования состояний с общим доступом (sstate). Возможность сборки и отладки отдельных компонент существенно облегчает разработку проектов.
Плановые выпуски. Основные выпуски системы происходят каждые 6 месяцев, приблизительно в октябре и апреле. Для двух последних выпусков поддерживаются точечные обновления для устранения обнаруженных дефектов и уязвимостей. Такая предсказуемость важна для проектов на основе YP и позволяет разработчикам планировать свои действия.
Доступ в сообщество для индивидуалов и организаций. Для проектов с открытым кодом сообщество играет очень важную роль. Доступны форумы поддержки, опыт и активные разработчики, развивающие YP.
Воспроизводимость на двоичном уровне. YP позволяет точно указать зависимости и обеспечить очень высокий процент воспроизводимости на двоичном уровне (например, 99,8% для core-image-minimal). Если дистрибутив не задает извлекаемые пакеты и их порядок для поддержки зависимостей, другие системы сборки могут произвольно включать пакеты.
Манифест лицензирования. YP поддерживает манифест лицензий для просмотра людьми, которым нужно контролировать использование лицензий программ с открытым кодом (например, юристы компании).

2.1.2. Сложности

Ниже рассмотрены некоторые сложности, которые могут возникать при разработке с использованием YP.

Скорость обучения. YP требует изучения большого объема материала и имеет множество способов решения похожих задач. Это может вызывать трудности при выборе конкретного варианта из множества возможных.
Для понимания вносимых изменений могут потребоваться некоторые исследования. Помимо простого обучения для пониманию изменений, которые нужно внести в конкретный проект могут потребоваться значительные исследования. Краткую информацию, которая поможет перейти от пробного использования YP к разработке реальных проектов можно найти на сайте YP в документах What I wish I’d Known и Transitioning to a Custom Environment for Systems Development.
Рабочий процесс проекта может приводить к путанице. Рабочий процесс YP может оказаться запутанным, если его использовать для разработки традиционный серверных и пользовательских программ. В среде разработки пользовательских систем имеются механизмы для простого извлечения и установки новых пакетов, которые обычно содержат заранее собранные двоичные файлы, доступные на серверах Internet. При работе с YP нужно самостоятельно менять конфигурацию и добавлять дополнительные пакеты.
Работа в среде кросс-сборки может представиться неудобной. При разработке кода для работы на целевой платформе компиляция, исполнение и тестирование на реальной платформе могут выполняться быстрее, чем сборка BitBake на хосте разработки и последующее развертывание двоичных файлов на целевой платформе. Хотя YP поддерживает средства разработки на целевой системе, потребуются дополнительные шаги для переноса изменений в среду сборки YP. В YP поддерживается промежуточный вариант, включающий внесение изменений на хосте разработки в среде BitBake и развертывание на целевой системе только обновлений.

Система сборки YP OE поддерживает стандартные форматы пакетов (RPM, DEB, IPK, TAR). Эти пакеты можно развернуть на работающей целевой системе с использованием предоставляемых там утилит, таких как rpm.
Время первоначальной сборки может быть продолжительным. К сожалению долгой первоначальной сборки избежать невозможно по причине большого числа пакетов, собираемых изначально для создания полнофункциональной системы Linux. Однако после этой сборки механизм кэширования общего состояния (sstate) позволяет YP значительно ускорить последующую сборку измененных пакетов.

2.2. Модель уровней YP

Модель уровней YP является моделью разработки для создания дистрибутивов Linux встраиваемых систем и IoT, которая отличает YP от других простых систем сборки. Модель уровней поддерживает совместную работу и настройку конфигурации уровней. Уровни являются репозиториями, содержащими наборы инструкций, которые говорят системе сборки OE, что нужно делать. Уровни можно использовать многократно, обобщать и применять в совместной работе.

Уровни могут содержать изменения созданных ранее настроек или инструкций. Мощные средства переопределения позволяют настраивать созданные ранее коллегами или сообществом уровни в соответствии со своими требованиями.

Можно применять разные уровни для логического разделения информации в вашей сборке. Например, можно создать уровни для BSP, GUI, настройки дистрибутива, промежуточных программ (middleware) или пользовательских приложений. Включение сборки целиком в один уровень ограничивает и усложняет последующую настройку и повторное использование, а разделение информации по уровням помогает упросить это.

По возможности следует применять уровни BSP.
Следует ознакомиться со списком уровней, поддерживаемых Yocto Project или OE (здесь больше уровней, но они менее тщательно проверяются).
Уровни поддерживают включение технологий, аппаратных и программных компонент. Маркировка YP Compatible обеспечивает подтверждение минимального уровня стандартизации. YP Compatible применяется к продукции и программным компонентам, таким как BSP, совместимые с OE уровни и проекты с открытым кодом, что позволяет производителю использовать знаки активы YP.

Рассмотрим применение уровней на примере настройки конфигурации машины. Такие настройки обычно помещаются на отдельный уровень, называемый уровнем BSP. Кроме того, изолируем настройки машины от заданий и метаданных, которые поддерживают, например, новую среду GUI. Это разумней всего сделать на двух уровнях — один для конфигурации машины, другой для среды GUI. Важно понимать, что уровень BSP может вносить машинозависимые дополнения в среду GUI, не внося изменений непосредственно в уровень GUI. Это делается с помощью файлов дополнения BitBake (.bbappend), описанных ниже. Общая информация о структуре уровня BSP приведена в [4].

Каталог источников содержит базовые уровни и уровни BSP. Уровни из состава выпуска YP легко найти в каталоге источников по их именам, которые обычно начинаются с префикса meta-. Наличие префикса не требуется, но принято сообществом YP как стандартная практика.

Если посмотреть представление дерева репозитория poky, можно увидеть уровни meta, meta-skeleton, meta-selftest, meta-poky и meta-yocto-bsp. Процедуры создания уровней описаны в разделе Understanding and Creating Layers [1].

2.3. Компоненты и инструменты

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

2.3.1. Средства разработки

Ниже кратко описаны инструменты для разработки образов и приложений с использованием YP.

CROPS ³ — открытая среда кроссплатформенной разработки, использующая контейнеры Docker. CROPS предоставляет легко управляемую и расширяемую среду сборки программ для различной архитектуры, включая хосты Windows, Linux и Mac OS X.
devtool — инструмент с консольным интерфейсом, являющийся основной частью расширяемого SDK (eSDK⁴). Можно применять devtool для сборки, тестирования и создания пакетов программ в рамках eSDK. Инструмент можно использовать для интеграции сборки в образ, создаваемый системой сборки OE.

Инструмент devtool поддерживает множество команд, которые позволяют добавлять, изменять и обновлять задания. Как и в системе сборки OE, задание в devtool представляет программный пакет. Команда devtool add позволяет создать задание автоматически. Команда devtool modify использует указанное имеющееся задание для определения источника исходных кодов и способа наложения изменений (patch). В обоих случаях среда настраивается так, чтобы при сборке задания использовалось дерево исходных кодов, находящееся под вашим контролем, что позволяет вносить в код изменения. По умолчанию новые задания и исходный код для них помещаются в каталог workspace файловой структуры eSDK. Команда devtool upgrade обновляет имеющееся задание с учетом внесенных в исходный код изменений. Работа с devtool подробно описана в разделе Using devtool in Your SDK Workflow [2].
Расширяемый комплект для разработки программ (eSDK) обеспечивает инструменты и библиотеки для кросс-разработки, адаптированные для создания конкретного образа. Пакеты eSDK позволяют легко добавлять приложения и библиотеки в образ, менять исходный код имеющихся компонент, тестировать изменения на целевой платформе и интегрировать в систему сборки OE. Инструменты eSDK с набором команд devtool адаптированы для среды YP. Описание eSDK приведено в [2].
Toaster — web-интерфейс для системы сборки YP OE, позволяющий настраивать и запускать сборку, а также просматривать ее результаты. Описание Toaster приведено в [6].

2.3.2. Инструменты для повышения производительности работы

Auto Upgrade Helper — утилита, применяемая с системой сборки OE (BitBake и OE-Core) для автоматического заданий на основе новой версии опубликованных исходных кодов.
Recipe Reporting System отслеживает версии заданий, доступные для YP. Основной задачей утилиты является помощь в поддержке заданий и динамическое рецензирование проекта. Система работает на основе web-сайта OpenEmbedded Layer Index, где индексируются уровни OpenEmbedded-Core.
Patchwork является ветвью проекта OzLabs и представляет собой web-систему отслеживания для оптимизации процесса внесения вкладов в проект. YP использует Patchwork для обслуживания правок (patch), выпускаемых в большом количестве для каждого выпуска.
AutoBuilder служит для автоматизации тестирования сборки и контроля качества (QA⁵). С помощью общедоступного сервиса AutoBuilder каждый может определить статус текущей ветви master в Poky. AutoBuilder работает на основе buildbot.

YP стремится быть передовым проектом в сфере открытого кода для автоматизации тестирования и проверки качества (QA). Проект приветствует публикацию разработчиками планов QA и тестирования, открыто демонстрирует свои планы и призывает разрабатывать инструменты для автоматизации процедур тестирования и QA на благо сообщества. Информацию о работе с AutoBuilder в YP можно найти по ссылке.
Cross-prelink. Предварительной ссылкой называется процесс упреждающего вычисления адресов загрузки и таблиц связей (компоновки) динамическим компоновщиком. Это позволяет повысить скорость запуска приложений и снизить расход памяти общими для множества приложений библиотеками.

Исторически предварительные кросс-ссылки являются вариантом предварительных ссылок, задуманных Jakub Jelínek много лет назад. Те и другие ссылки поддерживаются в разных ветвях одного репозитория. За счет предоставления эмулируемого динамического компоновщика в процессе работы (эмуляция ld.so из glibc) проект cross-prelink расширяет возможности программ с упреждающими ссылками, позволяя работать в средах стиля sysroot.

Динамический компоновщик вычисляет стандартные адреса загрузки на основе таких факторов, как адреса отображения, использование библиотек и конфликты библиотечных функций. Инструмент prelink использует эту информацию от динамического компоновщика для определения уникальных адресов загрузки двоичных файлов ELF⁶, являющихся динамическими библиотеками. Инструмент prelink меняет эти файлы ELF, используя заранее рассчитанные данные. Результатом является ускорение загрузки и зачастую экономия памяти, поскольку большая часть кода библиотеки может использоваться многократно со страниц COW⁷.

Исходный проект prelink поддерживает работу prelink лишь на динамических компоновщиках конечных целевых устройств. Это ограничение вызывает проблемы при разработке систем с кросс-компиляцией. Проект cross-prelink добавляет синтезированный динамический загрузчик, работающий на хосте и позволяющий создавать предварительные кросс-ссылки без запуска на целевой платформе с возможностью чтения и записи.
Pseudo — реализация в YP системы fakeroot, используемой для запуска команд в среде, которая представляется имеющей привилегии root.

В процессе сборки может потребоваться выполнение операций с полномочиями системного администратора. Например, может потребоваться установка принадлежности (владения) и прав доступа для файлов. Инструмент Pseudo можно использовать напрямую или через переменную среды LD_PRELOAD. В любом случае это позволяет выполнять операции с правами системного администратора, даже если его нет. Информация об инструменте приведена в параграфе 4.7. Fakeroot и Pseudo.

2.3.3. Компоненты системы сборки OE

BitBake является основной компонентой YP и применяется системой сборки OE для создания образов. Несмотря на это, BitBake поддерживается отдельно от YP.

BitBake является базовой машиной выполнения задач, обеспечивающей эффективное выполнение задач командного процессора и Python с возможностью параллельной работы с учетом зависимостей между задачами. Кратко говоря, BitBake — это машина сборки, работающая с заданиями в определенном формате для выполнения набора задач. Описание BitBake приведено в [7].
OpenEmbedded-Core (OE-Core) — базовый уровень метаданных (задания, классы и связанные с ними файлы), используемых основанными на OE системами, включая YP. Проекты YP и OpenEmbedded поддерживают OpenEmbedded-Core. Метаданные OE-Core доступны в репозитории YP Source Repositories.

Исторически метаданные OE-Core были интегрированы в YP через репозиторий эталонного дистрибутива Poky. После YP версии 1.0 было принято решение о совместной работе и использовании в YP и OE общего базового набора метаданных (OE-Core), который обеспечивает функциональность, ранее наблюдавшуюся в Poky. Это сотрудничество позволило достичь долгосрочной цели OE в части получения более строго контролируемого ядра с гарантией качества. Результат также соответствует цели YP получить меньшее, чем в иных системах число полнофункциональных инструментов.

Совместное использование ядра метаданных сделало Poky интеграционным уровнем на основе OE-Core, как показано на рисунке в разделе 2.1. Что такое YP. YP объединяет такие компоненты, как BitBake, OE-Core, сценарий «склеивания» и документацию по системе сборки.

2.3.4. Эталонный дистрибутив Poky

Poky является эталонным дистрибутивом YP и содержит систему сборки Open-Embedded (BitBake и OE-Core), а также набор метаданных, позволяющие начать создание своего дистрибутива. Рисунок в разделе 2.1. Что такое YP показывает связь Poky с другими частями YP.

Для использования инструментов и компонент YP можно загрузить (клонировать) Poky и использовать его в качестве исходной точки для создания своего дистрибутива. Poky не включает двоичных файлов и является примером создания дистрибутива Linux на базе исходных кодов. Дополнительные сведения о Poky приведены в разделе 2.5. Эталонный дистрибутив Poky.

2.3.5. Готовые пакеты

Matchbox — открытая базовая среда X Window для работы на встраиваемых системах, таких как карманные компьютеры, телевизионные приставки, киоски и т. п. с ограниченными размером экрана, механизмами ввода и системными ресурсами. Matchbox включает множество взаимозаменяемых и необязательных приложений, которые можно приспособить к конкретной платформе для расширения ее функциональности. Исходные коды Matchbox доступные в репозитории YP Source.
Opkg⁸ — облегченная система управления пакетами на основе itsy (ipkg), написанная на языке C и похожая в работе на Advanced Package Tool (APT) и Debian Package (dpkg). Менеджер пакетов предназначен для встраиваемых систем на основе Linux и применяется в проектах OpenEmbedded, OpenWrt и YP. Насколько это возможно, opkg поддерживает совместимость с ipkg и частично соответствует правилам Debian к файлам управления.

2.3.6. Архивные компоненты

Build Appliance — это образ виртуальной машины, позволяющий собрать и загрузить свой образ Linux для встраиваемой системы с помощью YP на платформе разработки, отличной от Linux. Исторически Build Appliance был вторым из 3 методов использования YP в системе, которая отличается от Linux.

Hob в настоящее время считается устаревшим и недоступен, поскольку с выпуска 2.1 YP поддерживает элементарный интерфейс GUI (Toaster), полностью заменивший Hob.
Build Appliance стал доступным после Hob, но никогда не был рекомендован в качестве повседневной среды разработки в YP. Build Appliance служит полезным вариантом пробной разработки в среде YP.
CROPS является финальным и наиболее эффективным решением для разработки с использованием YP на системах, отличных от Linux.

2.4. Методы разработки

Среда разработки YP обычно включает сборочных хост и целевую аппаратную платформу. Хост служит для сборки образов и разработки приложений, которые разворачиваются на целевой платформе для тестирования.

В этом разделе кратко описаны методы разработки, выбираемые при настройке хоста сборки. В зависимости от конкретных задач и операционной системы хоста сборки возможны несколько вариантов использования YP. Глава 3. Среда разработки YP содержит дополнительные сведения о среде разработки YP.

Хост Linux на сегодняшний день обеспечивает наилучшее решение для сборки. Linux является естественной операционной системой, позволяющей напрямую разрабатывать программы с использованием инструментов BitBake. Вся разработка может выполняться в привычной среде поддерживаемого дистрибутива Linux. Информация об организации хоста сборки в среде Linux приведена в разделе Setting Up a Native Linux Host [1].
CROss PlatformS (CROPS) на основе контейнеров Docker обычно применяется для организации хоста сборки под управлением других ОС (например, Microsoft® Windows™ или macOS®), однако можно использовать CROPS и в среде Linux.

CROPS является открытой системой кроссплатформенной разработки, которая обеспечивает управляемую и расширяемую среду для сборки двоичных файлов, предназначенных для разной архитектуры на хостах Windows, macOS или Linux. После настройки хоста сборки CROPS можно организовать среду разработки, имитирующую Linux. Информация о настройке хоста сборки CROPS дана в разделе Setting Up to Use CROss PlatformS (CROPS) [1].
Toaster позволяет разрабатывать программы с использованием YO, независимо от ОС хоста сборки. Toaster обеспечивает web-интерфейс для системы сборки YP Open-Embedded, позволяющий настраивать и запускать процесс сборки. Информация о сборке собирается и хранится в базе данных. Toaster можно применять для настройки и запуска сборки на нескольких удаленных серверах сборки. Описание Toaster приведено в [6].

2.5. Эталонный дистрибутив Poky

Poky (произносится Pock-ee) — эталонный дистрибутив YP или Reference OS Kit. Poky включает систему сборки OE (BitBake и OpenEmbedded-Core), а также набор метаданных для построения своего дистрибутива. Т. е. Poky задает базовую функциональность, требуемую для типовых встраиваемых систем, а также компоненты YP, позволяющие создать полезные двоичные образы. Poky объединяет репозитории BitBake, OpenEmbedded-Core (каталог meta), meta-poky, meta-yocto-bsp и документацию. Все эти компоненты Poky представлены в репозитории Source.

Полностью содержимое репозитория poky Git представлено в разделе Top-Level Core Components [3].

На рисунке представлено содержимое Poky.

BitBake — менеджер и планировщик задач, являющийся центральной частью системы сборки OE.
meta-poky содержит относящиеся к Poky метаданные.
meta-yocto-bspотносится к пакетам поддержки плат вYP (BSP).
Метаданные OpenEmbedded-Core (OE-Core) содержат конфигурации, определения глобальных переменных, классы общего пользования, средства подготовки пакетов и задания. Классы определяют инкапсуляцию и наследование логики сборки, задания являются логическими блоками собираемых программ и образов.
Документация содержит исходные файлы YP для создания руководств пользователя.

Хотя Poky задает полную спецификацию дистрибутива и проверен с помощью QA, он не является «готовой продукцией». Для работы с инструментами YP можно клонировать репозиторий Poky с помощью Git и далее пользоваться локальной копией для создания своего дистрибутива. Poky не включает готовых двоичных файлов и является лишь примером создания дистрибутива Linux из исходных кодов.

Poky выпускается каждые 6 месяцев со своей нумерацией версий. Основные выпуски выходят синхронно с выпусками YP, обычно весной и осенью. Дополнительная информация о планировании выпусков YP приведена в разделе Yocto Project Releases and the Stable Release Process [3].

Выше уже было сказано, что Poky является «принятой по умолчанию конфигурацией», которая служит исходной точкой для создания образа. Можно использовать Poky напрямую, создавая образы от самого простого до соответствующего требованиям Linux Standard Base (LSB) с эталонным пользовательским интерфейсом GNOME Mobile and Embedded (GMAE), который называется Sato.

Одним из важных свойств Poky является управление всеми аспектами сборки через метаданные. Можно расширить базовый образ, добавив уровни метаданных с расширенными функциями. Эти уровни могут добавлять программный стек в тип образа, добавлять пакеты поддержки плат (BSP) для оборудования, создавать новые типы образов.

Метаданные свободно группируются в конфигурационные файлы или задания для пакетов. Задание представляет собой набор метаданных, используемых BitBake для определения переменных или дополнительных задач при сборке. Файл задания содержит описание и версию задания, лицензию пакета и ссылку на репозиторий исходных кодов. Задание может также указывать процесс сборки с использованием autotools, make, distutils и т. п., при этом базовая функциональность будет определяться классами, наследуемыми из определений уровня OE-Core в ./meta/classes. В задании могут также указываться дополнительные задачи в качестве предварительных условий. Синтаксис заданий также поддерживает операторы _prepend и _append для расширения функциональности задач. Эти операторы добавляют код в начале или в конце задачи. Описание операторов этих BitBake приведено в разделе Appending and Prepending (Override Style Syntax) [7].

2.6. Работа с системой сборки OE

Система сборки OE использует для создания образов и SDK рабочий процесс (workflow), показанный на рисунке

Разработчики задают архитектуру, правила, правки (patch) и конфигурацию.
Система сборки извлекает исходные коды из указанных мест. Поддерживаются стандартные методы, включая архивы (tarball) и репозитории систем управления исходным кодом, таких как Git.
После загрузки исходных кодов система сборки распаковывает архивы в локальную рабочую область, где применяются исправления и общие операции по настройке конфигурации и компиляции программ.
Система сборки устанавливает программы во временную область, где применяется выбранный формат (DEB, RPM, IPK) подготовки пакетов.
Выполняются процедуры QA и проверки работоспособности на протяжении всего процесса сборки.
После создания двоичных файлов система сборки создает хранилище двоичных пакетов для создания окончательного образа корневой файловой системы.
Система сборки создает образ файловой системы и eSDK.

Более подробное описание рабочего процесса приведено в разделе 4.3. Концепции системы сборки OE.

2.7. Основные термины

Список используемых в YP приведен в разделе Yocto Project Terms [3], а здесь даны определения базовых терминов, которые помогут при изучении YP.

Файлы конфигурации содержат определения глобальных и пользовательских переменных, а также данные конфигурации оборудования. Эти файлы говорят системе сборки OE, что нужно собрать и что включить в образ для поддержки конкретной платформы.
Расширяемый комплект для разработки программ (eSDK) — это пользовательский SDK для разработчиков приложений, позволяющий встраивать свои изменения программ и библиотек в образ для использования другими разработчиками. Описание eSDK приведено в [2].
Уровень (Layer) — это набор связанных между собой заданий. Уровни позволяют объединить связанные между собой метаданные для настройки сборки, а также разделить информацию при сборках для разной архитектуры. Уровни являются иерархическими и могут переопределять спецификации других уровней. Можно взять любое число уровней из YP (см. список уровней на сайте) и настроить сборку, добавив свои уровни.

Подробное описание уровней приведено в разделе Understanding and Creating Layers [1], а уровни BSP дополнительно рассмотрены в разделе BSP Layers [4].
Метаданные служат важнейшим элементом YP, используемым для создания дистрибутива Linux, и содержатся в файлах, которые система сборки OE анализирует в процессе создания образа. В общем случае метаданные включают задания, файлы конфигурации и другую информацию, которая относится к самим инструкциям сборки, а также данные для выбора цели сборки. Метаданные включают также команды и данные, используемые для указания используемых версий программ, источников кода, применяемых исправлений и дополнений, которые служат для исправления ошибок или настройки программ под конкретную ситуацию. Важный для работы базовый набор проверенных метаданных содержится в OpenEmbedded-Core.
Система сборки OE, которую иногда называют BitBake или просто «система сборки».

BitBake является планировщиком и машиной выполнения задач, которая выполняет синтаксический разбор инструкций (задания) и данных конфигурации, создавая дерево зависимостей для компиляции, планирует компиляцию включенного кода, а затем выполняет сборку пользовательского образа Linux (дистрибутива). BitBake по своей функциональности напоминает make.

В процессе сборки отслеживаются зависимости и выполняется естественная (native) или кросс-компиляция пакетов. В качестве первого шага кросс-сборки предпринимается попытка создания набора инструментов кросс-компиляции (eSDK), подходящего для целевой платформы.
OpenEmbedded-Core (OE-Core) — это набор метаданных, включающий задания, классы и связанные с ними файлы, которые являются общими для множества разных систем, основанных на OE, включая YP. OE-Core представляет собой подмножество репозитория, разработанного сообществом OE, включающее наиболее часто применяемые задания. Результатом сокращения стал строго контролируемый набор заданий с гарантированным качеством. Метаданные доступны в каталоге meta репозитория исходных кодов YP.
Пакеты. В контексте YP пакетами называют задания, создаваемые BitBake (выполненные задания). Пакет обычно содержит двоичные файлы, скомпилированные из исходных кодов задания.

Следует отметить, что трактовка термина «пакет» может включать некоторые нюансы. Например, пакеты, упоминаемые в разделе Required Packages for the Build Host [3], являются скомпилированными двоичными файлами, установка которых расширяет функциональность дистрибутива Linux.

Следует также отметить, что исторически задания в YP назывались пакетами, поэтому имена некоторых переменных BitBake (например PR, PV, PE) не совсем корректны.
Poky является эталонным дистрибутивом для встраиваемых систем и эталонной тестовой конфигурацией. Poky включает в себя:

- дистрибутив с базовой функциональностью, служащий для иллюстрации настройки дистрибутивов;
- средства тестирования компонент YP (Poky применяется для проверки пригодности YP);
- средства загрузки YP.

Poky не является законченным дистрибутивом и служит лишь отправной точкой для создания дистрибутива. Poky представляет собой интеграционный уровень на основе OE-Core.

Задание (Recipe) представляет собой наиболее распространенную форму метаданных и содержит список настроек и задач (инструкций) для сборки пакетов, которые включаются в образ. Задание описывает местоположение исходного кода и применение к нему исправлений (patch), а также зависимости от библиотек или других заданий, конфигурацию и опции компиляции. Связанные между собой заданий образуют уровень.

Глава 3. Среда разработки YP

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

3.1. Философия программ с открытым кодом

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

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

Типичным примером проекта с открытым кодом является ядро Linux, которое было задумано и создано финским студентом Линусом Торвальдсом (Linus Torvalds) в 1991 г. А примером закрытого кода может служить семейство операционных систем Windows® от Microsoft® Corporation.

В Wikipedia приведено хорошее историческое описание философии открытого кода.

3.2. Хост разработки

Для работы с YP требуется хост разработки или сборочный хост. Поскольку целью YP является создание образов и приложений для работы на встраиваемых системах, процесс разработки и сборки происходит не на той системе, где будет применяться образ или программа, а на хосте разработки. Большинство людей считает что в качестве сборочного хоста лучше всего использовать машину с операционной системой Linux, однако можно работать и с системами Mac или Windows, применяя CROPS на базе контейнеров Docker. После организации машины CROPS вы получите доступ к среде, похожей на среду хоста разработки Linux. Организация машины CROPS описана в разделе Setting Up to Use CROss PlatformS (CROPS) [1].

На хосте разработки Linux также требуется ряд операций для подготовки к работе с YP. Дистрибутив Linux должен поддерживать YP. Кроме того, потребуется установить на хосте ряд пакетов, требуемых для разработки с использованием YP. Процедуры установки описаны в разделе Setting Up a Native Linux Host [1].

После организации хоста разработки YP можно пользоваться несколькими вариантами работы, описанными ниже.

Командная среда BitBake. Традиционный процесс разработки в YP включает использование системы сборки OE, которая включает командный интерфейс BitBake на хосте разработки. Интерфейс доступен как в среде Linux, так и на машинах CROPS. В обоих случаях образы создаются, изменяются и собираются в командной среде, использующей компоненты и инструменты, доступные в дистрибутиве Linux и YP. Общее описание процедур сборки приведено в разделе Building a Simple Image [1].
Разработка BSP включает использование YP для создания и тестирования уровней, позволяющих разрабатывать образы и приложения для конкретного оборудования. Для разработки BSP требуются дополнительные операции по организации хоста сборки, описанные в разделе Preparing Your Build Host to Work With BSP Layers [4].
Разработка ядра с использованием YP чаще всего выполняется с помощью инструмента devtool,существенно упрощающего работу и ускоряющего процесс. Подготовка хоста разработки к работе с ядром описана в разделе Preparing the Build Host to Work on the Kernel [9].
Интерфейс Toaster системы сборки OE обеспечивает средства для настройки и запуска сборки. Информация о сборке сохраняется в базе данных. Интерфейс Toaster позволяет настраивать и запускать сборку на нескольких удаленных сборочных хостах. Установка, настройка и использование Toaster описаны в [6].

3.3. Репозитории исходных кодов YP

Команда YP поддерживает репозитории всех файлов на сайте http://git.yoctoproject.org. Репозитории организованы по категориям, таким как IDE Plugins, Matchbox, Poky, Yocto Linux Kernel и т. п. Можно выбрать любой элемент в колонке Name и увидеть внизу страницы ссылку URL для клонирования репозитория Git с выбранным элементом. Наличие локальной копии репозитория Git в каталоге исходных кодов, которые обычно именуется poky, позволяет вносить изменения, обеспечивая в конечном итоге развитие инструментов YP, BSP и т. п..

Для любого из поддерживаемых выпусков YP можно перейти на сайт Yocto Project и выбрать вариант DOWNLOADS в меню SOFTWARE для загрузки архива репозитория repository, поддерживаемых BSP и инструментов YP. Распаковка этих архивов обеспечит локальные копии файлов выпуска.

Для установки каталога источников YP и файлов поддерживаемых BSP (например, meta-intel) рекомендуется использовать Git.
Следует всегда применять соответствующие ветви репозитория выбранного BSP и исходного кода (poky). Например, при выборе ветви master для poky и работе с meta-intel нужно выбрать ветвь master в meta-intel.

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

Репозиторий исходных кодов включает категории IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel и Yocto Metadata Layer. Можно создать локальные копии каждого из репозиториев Git. Работа с репозиториями Git описана в разделе Accessing Source Repositories [1].

Список выпусков содержит Poky, Pseudo, установщики инструментов кросс-разработки, а также компоненты поддержки и все выпуски YP в форме образов или архивов. Загрузка и распаковка этих файлов создает не локальную копию репозитория Git, а «снимок» определенного выпуска или образа.

Работа с такими файлами описана в разделе Accessing Index of Releases [1].
Страница DOWNLOADS на сайте Yocto Project Website, доступная через меню SOFTWARE, позволяет загрузить любой выпуск YP, инструменты и BSP в виде архивов (tarball), подобных представленным в списке выпусков.

Работа со страницей DOWNLOADS описана в разделе Using the Downloads Page [1].

3.4. Работа с Git в YP

Разработка с использованием YP требует применения Git — открытой распределенной системы управления исходными кодами,которая применяется во многих средах коллективной разработки. В этом разделе описан процесс работы с YP и Git, в частности, описаны базовые методы, роли и операции в среде коллективной разработки.

Файлы YP поддерживаются с использованием Git в ветвях (branch) и Git отслеживает каждое изменение и структуру ветвления. Хотя применение Git для этого не обязательно, многие открытые проекты используют такой подход.

В YP сопровождающий (maintainer) отвечает за целостность ветви master данного репозитория Git. Ветвь master является «восходящим» (upstream) репозиторием, на основе которого выполняется сборка для текущего состояния проекта. Сопровождающий отвечает за принятие изменений от других разработчиков и организацию базовой структуры ветви в соответствии со стратегией выпусков и т. п. Способы выяснения сопровождающих, которые отвечают за конкретную ветвь (и поддерживают ее) описаны в разделе Submitting a Change to the Yocto Project [1].

Репозиторий YP poky включает также «восходящий» репозиторий Git с именем poky-contrib. Можно увидеть все ветви этого репозитория через web-интерфейс Source Repositories в области Poky Support. В этих ветвях содержатся изменения (commit) в проекте, которые были представлены или зафиксированы командой разработки YP и членами сообщества, участвующими в проекте. Сопровождающий определяет пригодность изменений для переноса из ветвей contrib в ветвь master репозитория Git.

Разработчики (включая членов сообщества) создают и поддерживают клонированные репозитории разрабатываемых ветвей, которые размещаются локально на их платформах и служат для подготовки изменений. Когда разработчик удовлетворен полученными результатами, он «выталкивает» (push) эти изменения в подходящий репозиторий contrib.

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

Имеется несколько формализованных методов, с помощью которых разработчики фиксируют изменения и помещают их в область contrib, а затем просят сопровождающего включить их в разрабатываемую ветвь. Этот процесс называется представлением изменений (submitting a patch или submitting a change). Процедуры описаны в разделе Submitting a Change to the Yocto Project [1].

Таким образом организуется «единая точка входа» в ветвь master или разрабатываемую ветвь репозитория Git, контролируемая сопровождающим проект лицом. Разработчики независимо создают, тестируют и представляют изменения в области contrib для проверки сопровождающим, который выбирает включаемые в основной проект правки.

Несмотря на уникальность каждой среды разработки, имеются общие методы «бесшовной» стыковки результатов, которые кратко описаны ниже. Более полное описание процессов приведено в [10].

Внесение изменений небольшой группой. Лучше вносить изменения небольшими порциями, нежели собирать вместе множество разнородных изменений. Это не только позволяет управлять изменениями, но и упрощает сопровождающему решение вопросов о принятии или отклонении правок.
Завершенные наборы изменений. Хорошим тоном является поддержка состояния репозитория, позволяющего в любой момент собрать проект. Иными словами, не следует фиксировать незавершенные изменения. Каждая фиксация должна обеспечивать возможность сборки проекта.
Свободное использование ветвей. При работе с локальным репозиторием Git легко создать, использовать и затем удалить ветвь. Локальным ветвям можно давать произвольные имена, например, связывая их со свойством или изменением, которое задает ветвь. После слияния изменения с основной локальной ветвью временную ветвь можно просто удалить.
Слияние изменений. Команда git merge позволяет принять изменения из одной ветви в другую. Это особенно полезно при работе нескольких человек над разными частями одной функции или изменения. При слиянии автоматически обнаруживаются любые конфликты, которые могут возникать в результате изменения одной строки несколькими участниками работы.
Управление ветвями. Поскольку работа с ветвями проста, следует применять ветви для указания различных уровней готовности кода. Например, можно сделать ветвь work для разработки, test — для тестирования и изменения кода по результатам тестов, stage — для кода, готового к представлению и д. д. По мере развития проекта код из разных ветвей может сливаться.
Сценарии Push и Pull. Процесс «тяни-толкай» (push-pull) основан на концепции разработчиков, «вталкивающих» (push) свои локальные фиксации в удаленный репозиторий. В процессе также участвуют разработчики, «вытягивающие» (pull) известные состояния проекта в свой локальный репозиторий разработки. Процесс позволяет загрузить фиксации других разработчиков из восходящего репозитория, обеспечивая наличие самых свежих версий. YP включает сценарии create-pull-request и send-pull-request для использования этого процесса. Сценарии размещаются в каталоге scripts дерева источников. Работа со сценариями описана в разделе Using Scripts to Push a Change Upstream and Request a Pull [1].
Процесс исправления (Patch Workflow) позволяет уведомить сопровождающего по электронной почте о наличии изменений (правок — patch), которые вы считаете нужным включить в ветвь master репозитория Git. Для отправки изменений формируется patch-файл и передается по электронной почте с помощью команд git format-patch и git send-email. Информация о работе с этими сценариями приведена в разделе Submitting a Change to the Yocto Project [1].

3.5. Git

YP широко использует Git — открытую систему управления версиями исходных кодов. Git поддерживает распределенную и нелинейную разработку и может применяться для крупных проектов. Полезно разобраться с тем, как Git отслеживает проекты и как применять Git при работе в среде YP. Ниже приведен краткий обзор работы с Git и описания некоторых важных команд Git. Более полная информация доступна на сайте Git.

При необходимости установки Git лучше сделать это через менеджер пакетов используемого дистрибутива. Доступные для загрузки файлы можно найти на странице загрузок Git. Дополнительная информация приведена в разделе Locating Yocto Project Source Files [1].

3.5.1. Репозитории, теги и ветви

Как отмечено в разделе 3.4. Работа с Git в YP, YP поддерживает репозитории исходных кодов на сайте http://git.yoctoproject.org. В web-интерфейсе видно, что каждый элемент хранится в своем репозитории Git.

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

Репозиторий Git представляет все действия по разработке данного проекта. Например, репозиторий poky содержит все изменения и разработки для этого проекта за весь срок его существования. Репозиторий поддерживает полную историю изменений.

Можно создать локальную копию репозитория путем его клонирования с помощью команды git clone. Клонирование создает локальную копию репозитория в системе разработки. С этой копией можно вести разработку на своем хосте. Примеры клонирования репозиториев Git даны в разделеLocating Yocto Project Source Files [1].

Важно понимать, что Git отслеживает изменения содержимого, а не файлов. Для организации разных направлений разработки применяются ветви. Например, репозиторий poky имеет несколько ветвей, включая zeus, master и множество ветвей прошлых выпусков YP. Можно увидеть эти ветви на странице http://git.yoctoproject.org/cgit.cgi/poky/, щелкнув ссылку […] в разделе Branch.

Каждая из этих ветвей представляет конкретную область разработки. Ветвь master представляет текущее (или наиболее свежее) состояние основной разработки, а прочие — те или иные ответвления процесса.

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

     $ cd ~
     $ git clone git://git.yoctoproject.org/poky
     $ cd poky
     $ git checkout -b zeus origin/zeus

В этом примере после перехода в домашний каталог команда git clone создает локальную копию репозитория poky. По умолчанию Git выбирает для работы ветвь master. После перехода в каталог локального репозитория poky команда git checkout создает и выбирает локальную ветвь zeus, отслеживающую восходящую ветвь origin/zeus. Внесенные в эту ветвь изменения будут в конечном итоге влиять на ветвь zeus восходящего репозитория poky.

Важно понимать, что при создании и выборе локальной рабочей ветви по имени, локальная среда будет соответствовать «подсказке» (tip) этой конкретной ветви разработки на момент создания локальной ветви и может отличаться от ветви master в восходящем репозитории. Иными словами, создание и выбор локальной ветви по имени zeus будет отличаться от выбора ветви master в репозитории. Далее будет описано, как создать локальный снимок выпуска YP.

Git использует теги для маркировки конкретных изменений в структуре ветвей репозитория. Обычно теги служат для маркировки специальных точек, таких как финальное изменение (или фиксация) перед выпуском проекта. Можно увидеть теги репозитория poky на странице http://git.yoctoproject.org/cgit.cgi/poky/ по ссылке […] в разделе Tag. Важными тегами poky являются jethro-14.0.3, morty-16.0.1, pyro-17.0.0 и zeus-22.0.0, представляющие выпуски YP.

В локальной копии репозитория Git сохраняется доступ ко всем тегам восходящего репозитория. Можно создавать и выбирать локальную рабочую ветвь Git по имени тега. В этом случае будет создан снимок репозитория Git, отражающий состояние файлов на момент внесения изменений, связанных с тегом. Чаще всего это применяется для выбора рабочей ветви, соответствующей определенному выпуску YP. Пример такого выбора приведен ниже.

     $ cd ~
     $ git clone git://git.yoctoproject.org/poky
     $ cd poky
     $ git fetch --tags
     $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0

Здесь каталог верхнего уровня локального репозитория YP называется poky. После перехода в этот каталог команда git fetch делает все теги восходящего репозитория доступными локально. Команда git checkout после этого создает и выбирает ветвь с именем my-rocko-18.0.0, основанную на восходящей ветви, в которой HEAD соответствует фиксации репозитория с тегом rocko-18.0.0. Файлы в локальном репозитории будут совпадать с файлами конкретного выпуска YP с указанным тегом в восходящем репозитории Git. Важно понимать, что при создании и выборе локальной ветви на основе тега среда будет соответствовать конкретному момент а не всей ветви разработки.

3.5.2. Базовые команды

Широкий набор команд Git позволяет управлять изменениями и участвовать в совместной работе над проектами. Для управления небольшим набором базовых операций и рабочих процессов следует понять базовую философию Git. Не нужно быть экспертов в Git для работы с программой. Краткий справочник по командам Git доступен по ссылке.

Ниже описаны некоторые базовые команды Git, позволяющие начать работу. Команды указаны без аргументов, полное описание доступно в документации Git.

git init

Инициализирует пустой репозиторий Git. Репозитории Git не могут использоваться без структуры .git.

git clone

Создает локальную копию репозитория Git данного разработчика или восходящего репозитория.

git add

Локально помещает обновленное содержимое файлов в индекс, применяемый в Git для отслеживания изменений. Перед фиксацией все измененные файлы должны быть подготовлены.

git commit

Создает локальную «фиксацию» с документированием внесенных изменений. Фиксируются лишь изменения, добавленные в индекс. Фиксации служат для сохранения истории, определения сопровождающим приемлемости изменений для проекта и в конечном итоге для переноса локальных изменений в репозиторий проекта.

git status

Сообщает о всех измененных файлах в каталоге и индексе, указывая измененные, но не включенные в индекс файлы и файлы, ожидающие фиксации.

git checkout branch-name

Меняет локальную рабочую ветвь в предположении ее наличия. Похожа на команду оболочки cd.

git checkout –b working-branch upstream-branch

Создает и выбирает рабочую ветвь working-branch на локальной машине с отслеживанием ветви upstream-branch. Можно использовать локальную ветвь для изоляции своей работы при добавлении конкретных свойств или изменений. Изоляция ветвей упрощает удаление невостребованных изменений.

git branch

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

git branch -D branch-name

Удаляет имеющуюся локальную ветвь. Для удаления локальной ветви branch-name
она не должна быть выбрана.

git pull --rebase

Извлекает данные из восходящего репозитория Git и помещает их в локальный репозиторий. Команда служит для синхронизации локального репозитория с базовым (например, с ветвью master). Опция —rebase гарантирует сохранение всех локальных фиксаций при синхронизации.

git push repo-name local-branch:upstream-branch

Передает все зафиксированные локальные изменения в восходящий репозиторий Git, отслеживаемый локальным репозиторием. Сопровождающий просматривает эти репозитории для слияния изменений с нужной ветвью.

git merge

Объединяет или добавляет обновления из одной ветви локального репозитория с другой ветвью. При создании локального репозитория Git принятая по умолчанию ветвь называется master. Типичный рабочий процесс включает создание временной ветви на основе master, служащей для изоляции работы. Можно внести нужные изменения в эту временную ветвь, проиндексировать и зафиксировать их локально, переключиться на ветвь master и воспользоваться командой git merge для применения изменений в изолированной ветви к текущей выбранной ветви (например, master). Если временная ветвь после слияния уже не нужна, ее можно удалить.

git cherry-pick commits

Выбирает и применяет указанные фиксации (commit) из одной ветви в другую. Бывают моменты, когда невозможно слить все изменения в одной ветви с другой ветвью, но нужно применить некоторые изменений.

gitk

Обеспечивает графический интерфейс (GUI) для просмотра ветвей и изменений в локальном репозитории Git. Команда дает хорошее графическое представление изменений в локальном репозитории. Для работы с командой нужно установить пакет gitk.

git log

Выводит историю фиксация для репозитория независимо от их публикации в восходящем репозитории.

git diff

Выводит построчные различия между локальным рабочим файлом и таким же файлом в понимании Git.

3.6. Лицензии

Поскольку проекты с открытым кодом публично доступны, они распространяются с теми или иными лицензиями. Эволюция лицензий для открытых (Open Source) и бесплатных программ (Free Software) представляет исторический интерес. Ниже приведены две ссылки на информацию о развитии и изменении таких лицензий.

В общем случае YP широко распространяется по лицензии Massachusetts Institute of Technology (MIT), разрешающей использовать программу в фирменных (proprietary) программах при включении в программу лицензии. Лицензия MIT совместима с GNU General Public License (GPL). Правки в YP обычно используют схему восходящего лицензирования. Информация о лицензии MIT доступна по ссылке, как и лицензия GNU GPL.

При создании образа с помощью YP процесс сборки использует известный список лицензий для обеспечения соответствия. Этот список можно найти в дереве источников (meta/files/common-licenses). По завершении сборки список всех найденных и использованных при сборке лицензий помещается в каталог сборки (tmp/deploy/licenses).

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

Базовый список лицензий, используемый процессом сборки, является комбинацией списка SPDX⁹ и проектов Open Source Initiative (OSI). SPDX Group является рабочей группой Linux Foundation, которая поддерживает спецификацию стандартного формата для передачи компонент, лицензий и авторских прав, связанных с программным пакетом. OSI является корпорацией, посвятившей себя определению исходного кода (OSD¹⁰) и усилиям по рассмотрению и утверждению лицензий, соответствующих OSD. Информацию, которая может помочь в поддержке соответствия лицензиям в жизненном цикле продукции, созданной с использованием YP, можно найти в разделе Maintaining Open Source License Compliance During Your Product’s Lifecycle [1].

Глава 4. Концепции YP

В этой главе рассмотрены концепции, выходящие за рамки практических и справочных руководств. Описаны такие компоненты, как рабочий процесс системы сборки OE, инструменты кросс-разработки, кэш общих состояний и т. п.

4.1. Компоненты YP

Среда выполнения задач BitBake вместе с разными типами конфигурационных файлов образует OpenEmbedded-Core. В этом разделе рассматриваются указанные компоненты с описанием их использования и взаимодействий. BitBake обеспечивает синтаксический анализ и выполнение файлов данных, которые могут иметь несколько типов:

задания обеспечивают детали для конкретных частей программ;
данные классов содержат абстракции общей информации сборки (например, способ сборки ядра Linux);
данные конфигурации задают машинозависимые настройки, правила и т. п., выступая в качестве склеивающей субстанции для сборки.

BitBake знает, как объединить множество источников данных и рассматривает каждый источник данных как уровень. Уровни описаны в разделе Understanding and Creating Layers [1]. Дополнительные сведения о взаимодействии базовых компонент приведены в разделе 4.3. Концепции системы сборки OE.

4.1.1. BitBake

BitBake является основным инструментом системы сборки OE и отвечает за синтаксический анализ метаданных, генерацию на их основе списка задач и последующее выполнение этих задач. В этом параграфе приведено краткое описание BitBake, а полную информацию можно найти в [7]. Для просмотра списка поддерживаемых BitBake можно воспользоваться командой bitbake -h или bitbake —help.

Чаще всего BitBake применяется в форме bitbake packagename, где packagename задает имя собираемого пакета (часто называется целью — target). Зачастую имя пакета совпадает с первой частью имени файла задания (например, foo для задания foo_1.3.0-r0.bb). Так, для обработки задания Smatchbox-desktop_1.2.3.bb следует ввести команду

     $ bitbake matchbox-desktop

Может существовать несколько версий задания matchbox-desktop и BitBake выберет одно из них на основе конфигурации дистрибутива. Более подробно процедура выбора описана в разделе Preferences [7].

BitBake пытается заранее выполнить все задачи, от которых имеется зависимость. Например, перед сборкой matchbox-desktop программа BitBake может собирать кросс-компилятор и glibc, если они еще не собраны.

Следует обратить внимание на опцию BitBake -k (или —continue), которая задает попытку продолжать работу даже после возникновения ошибки. Обычно ошибка прерывает сборку и задание, в котором она возникла, и зависящие от него задания не могут быть повторены, однако эта опция позволяет обработать другие зависимости.

4.1.2. Задания

Файлы с расширением .bb содержат задания (recipe). В общем случае задание включает данные об одной программе, включающие местоположение исходного кода, применяемые к нему исправления (если они имеются), особые опции настройки, способ компиляции исходных файлов и способ создания выходного пакета.

Иногда для обозначения заданий используется термин «пакет» (package), однако чаще пакетом называют сформированный результат системы сборки OE (т. е. файлы .ipk или .deb).

4.1.3. Классы

Файлы классов (.bbclass) содержат информацию, применимую к множеству заданий. Примером может служить класс autotools, который содержит общие настройки для программ с автоматической настройкой (Autotools). Работа с классами описана в разделе Classes [3].

4.1.4. Конфигурации

Конфигурационные файлы (.conf) определяет переменные, управляющие процессом сборки OE. Эти файлы размещаются в нескольких областях для настройки машины, дистрибутива, параметров компиляции, общих параметров конфигурации и пользовательских параметров в файле conf/local.conf каталога сборки.

4.2. Уровни

Уровнями называют репозитории связанных метаданных (наборов инструкций) указывающих системе сборки OE как собирать цель. Модель уровней YP облегчает совместную работу, обмен, настройку и многократное использование настроек в среде разработки YP. Уровни логически разделяют информацию разных проектов. Например, можно создать уровень для хранения всех конфигураций, связанных с определенной аппаратной платформой. Изоляцию аппаратно-зависимых конфигураций позволяет использовать другие метаданные совместно, используя свой уровень аппаратных метаданных для каждой целевой платформы.

В среде разработки YP имеется множество уровней, которые доступны по ссылкам Yocto Project Curated Layer Index и OpenEmbedded Layer Index.

По соглашению уровни в YP имеют определенную форму и соответствие заданной структуре позволяет BitBake принимать в процессе сборки допущения о местоположении разных типов метаданных. Процедуры и инструменты для работы с уровнями описаны в разделе Understanding and Creating Layers [1].

4.3. Концепции системы сборки OE

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

В общем случае рабочий процесс сборки включает несколько функциональных областей.

Пользовательская конфигурация задает метаданные, используемые для управления процессом сборки.
Уровни метаданных содержат информацию о программах, машине и дистрибутиве (метаданные).
Исходные файлы с «восходящими» выпусками программ, локальными проектами и SCM.
Система сборки, работающая под управлением BitBake. Этот блок определяет извлечение исходного кода, применение правок (patch), компиляцию, анализ вывода для создания пакетов, создание и проверку пакетов, генерацию образов, а также генерацию инструментов кросс-разработки.
Источники (хранилища) пакетов — каталоги с выходными пакетами (RPM, DEB, IPK), которые используются при создании образа или SDK на выходе системы сборки. Эти хранилища могут копироваться и совместно использоваться через web-сервер или иным путем для расширения или обновления имеющихся образов или устройств в процессе работы, если на них включено управление пакетами.
Образы, создаваемые рабочим процессом.
SDK — инструменты кросс-разработки, создаваемые BitBake вместе с образом или отдельно.

4.3.1. Пользовательская конфигурация

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

BitBake нужны некоторые базовые файлы конфигурации для выполнения сборки. Минимальный набор конфигурационных данных хранится в каталоге build/conf дерева источников, которое здесь для простоты называется каталогом Poky. При клонировании репозитория Poky или загрузке и распаковке выпуска YP можно указать для дерева источников любой желаемый каталог (здесь предполагается каталог poky).

Репозиторий Poky — это, прежде всего, объединение имеющихся репозиториев, а не канонический «восходящий» источник. Уровень meta-poky в Poky содержит каталог conf с примерами файлов конфигурации, которые могут служить основой для реальных файлов, применяемых сценарием oe-init-build-env для организации среды сборки. Выполнение этого сценария создает каталог сборки, если его еще нет. BitBake использует каталог сборки при работе. Этот каталог включает подкаталог conf с принятыми по умолчанию файлами local.conf и bblayers.conf. Эти два файла создаются автоматически, если их еще не было к моменту запуска сценария организации среды сборки.

Поскольку репозиторий Poky является объединением других репозиториев, некоторые пользователи могут применять сценарий инициализации (oe-init-build-env) в контексте репозиториев OpenEmbedded-Core и BitBake, а не Poky. В зависимости от использованного сценария вызываются разные субсценарии организации каталога сборки (Yocto или OE). В частности, сценарий scripts/oe-setup-builddir в каталоге poky организует каталог сборки и при необходимости помещает в него файлы, подходящие для среду разработки YP. Этот сценарий использует переменную $TEMPLATECONF для определения конфигурационных файлов, которые нужно найти.

Файл local.conf содержит множество переменных, задающих среду сборки, часть которых перечислена ниже. Конфигурационный файл local.conf, создаваемый по умолчанию сценарием настройки среды сборки, описан в файле local.conf.sample уровня meta-poky.

MACHINE выбирает целевую машину.
DL_DIR указывает каталог для загрузки файлов.
SSTATE_DIR указывает каталог общих состояний.
TMPDIR указывает каталог для вывода результатов сборки.
DISTRO задает политику для дистрибутива.
PACKAGE_CLASSES задает параметры создания пакетов.
SDKMACHINE указывает целевую архитектуру для SDK.
EXTRA_IMAGE_FEATURES задает дополнительные пакеты для включения в образ.

Эти параметры конфигурации можно задать также в файлах conf/site.conf и conf/auto.conf.

Файл bblayers.conf указывает системе сборки BitBake уровни, включаемые в процесс. По умолчанию этот файл содержит минимальный набор уровней, требуемых для сборки, однако в него можно вручную добавить любые нужные уровни. Работа с файлом bblayers.conf описана в разделе Enabling Your Layer [1].

Файлы site.conf и auto.conf сценарий организации среды не создает. Файл site.conf можно создать вручную, а файл auto.conf обычно создает autobuilder.

Файл site.conf можно использовать для настройки нескольких каталогов сборки. Например, при наличии нескольких сред сборки с общими свойствами здесь можно указать используемые по умолчанию свойства сборки. Хорошим примером служит задание формата пакетов через переменную PACKAGE_CLASSES.

Одним из вариантов применения файла conf/site.conf является преобразование переменной BBPATH для включения пути в conf/site.conf. Тогда BitBake при просмотре метаданных с использованием BBPATH найдет файл conf/site.conf и применит заданную в нем конфигурацию. Для переопределения конфигурации в отдельном каталоге сборки нужные параметры задаются в файле conf/local.conf внутри этого каталога.
Файл auto.conf обычно создает autobuilder, помещая в него настройки из conf/local.conf или conf/site.conf.

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

При запуске сборки командой bitbake target программа BitBake сортирует конфигурации и в конечном итоге задает среду сборки. Важно понимать, что система сборки OE читает файлы конфигурации в определенном порядке — site.conf, auto.conf и local.conf. При этом применяются обычные правила для операторов присваивания, описанные в разделе Syntax and Operators [7]. Благодаря заданному порядку анализа файлов конфигурации, можно задавать разные значения переменных. Например, в файлах auto.conf и local.conf могут быть заданы разные значения переменной variable1, а поскольку файл local.conf анализируется после auto.conf, variable1 получит значение из файла local.conf.

4.3.2. Метаданные, конфигурация машины и политики

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

В общем случае выделяют три три типа входной информации для уровней, описанных ниже.

Метаданные (.bb + правки). Уровни программ включают указанные пользователем задания, файлы исправлений (patch) и добавлений. Хорошим примером может служить уровень meta-qt5 из OpenEmbedded Layer Index. Этот уровень создан для версии 5.0 популярной среды кроссплатформенной разработки Qt для настольных, встраиваемых и мобильных систем.
Конфигурация BSP для машины. Уровни пакетов поддержи плат (BSP) задают машинозависимые конфигурации, относящиеся к конкретной целевой архитектуре. Хорошим примером служит уровень BSP из эталонного дистрибутива Poky (meta-yocto-bsp ).
Конфигурация политики. Уровни дистрибутивов (Distro) обеспечивают базовые правила для образа или SDK, собираемого с конкретным дистрибутивом. Например, в эталонном дистрибутиве Poky уровнем distro служит meta-poky. На уровне distro каталог conf/distro содержит конфигурационный файл дистрибутива (например, poky.conf ).

Отмеченные выше уровни показаны на рисунке.

Обычно все уровни используют похожую структуру, включая файл лицензии (например, COPYING.MIT), если уровень является распространяемым, файл README (хороший тон особенно для распространяемых уровней), каталог конфигурации и каталоги заданий. Общая структура уровней YP описана в разделе Creating Your Own Layer [1]. Применение уровней кратко рассмотрено в разделах 4.2. Уровни и 2.2. Модель уровней YP, где отмечено, что в некоторых областях может существовать множество уровней, работающих в YP. В Source Repositories уровни выделены в категорию Yocto Metadata Layers. Следует отметить, что в YP Source Repositories имеются уровни, не представленные в OpenEmbedded Layer Index, — это устаревшие или экспериментальные уровни.

BitBake применяет файл conf/bblayers.conf, являющийся частью пользовательской конфигурации, для поиска уровней, включаемых в сборку.

4.3.2.1. Уровень дистрибутива

Уровень дистрибутива задает правила для дистрибутива. Хорошим тоном является отделение этой конфигурации от пользовательских уровней. Параметры в conf/distro/distro.conf переопределяют некоторые установки, которые BitBake берет из файла conf/local.conf в каталоге сборки. Ниже приведено краткое описание содержимого уровня дистрибутива.

Файлы классов (.bbclass) задают общие функции, которые могут применяться заданиями дистрибутива. При наследовании класса заданием, оно получает все настройки и функции класса. Дополнительная информация о классах приведена в разделе Classes [3].
Параметры конфигурации включают файлы конфигурации уровня (conf/layer.conf) и дистрибутива (conf/distro/distro.conf), а также включаемые для дистрибутива файлы.
Каталоги recipes-* содержат задания и дополнения, влияющие на функциональность дистрибутива. Здесь размещаются файлы заданий и дополнений со специфической для дистрибутива конфигурацией, сценариями инициализации, заданиями для пользовательских образов и т. п. Примерами каталогов recipes-* служат recipes-core и recipes-extra. Иерархия и содержимое каталогов recipes-* могут меняться. Обычно здесь содержатся файлы заданий (*.bb) и добавления (*.bbappend), каталоги с конфигурационными файлами конкретного дистрибутива и т. п.

4.3.2.2. Уровень BSP

Уровень BSP включает конфигурации машин для целевых аппаратных платформ, задавая все, что относится к машине, для которой собирается образ или SDK. Для уровня определена общая структура и форма [4]. Для того, чтобы уровень BSP был совместим с YP, нужно выполнить ряд структурных требований.

Каталог конфигурации уровня BSP содержит файлы для машины (conf/machine/machine.conf) и уровня (conf/layer.conf). Остальная часть уровня относится к заданиям, разделенным по функциям — recipes-bsp, recipes-core, recipes-graphics, recipes-kernel и т. п.. Могут присутствовать метаданные для разных форм-факторов, графических подсистем и т. п.

4.3.2.3. Уровень программ

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

4.3.3. Источники

Чтобы система сборки OE могла создать образ или иную цель, она должна иметь доступ к исходным файлам. Метод организации исходных файлов зависит от проекта. Например, для выпущенных программ в проектах обычно используются архивы (tarball или иные файлы), которые фиксируют определенный выпуск. Для более динамичных и экспериментальных проектов могут применяться исходные файлы из репозитория SCM (например, Git). Извлечение файлов из репозитория позволяет контролировать состояние (выпуск) кода, который применяется для сборки. Может применяться и комбинация упомянутых вариантов, позволяющая потребителю выбрать источник файлов.

BitBake использует переменную SRC_URI для указания исходных файлов независимо от места их размещения. Эта переменная должна указываться в каждом задании.

Другим важным параметром выбора исходных файлов служит переменная DL_DIR,указывающая область кэширования с ранее загруженными файлами. Можно также задать системе сборки OE (переменная BB_GENERATE_MIRROR_TARBALLS) создание архивов (tarball) репозиториев Git (по умолчанию не выполняется) и запись их в DL_DIR.

Разумное использование каталога DL_DIR может сократить время сборки при использовании файлов из Internet. Разумно размещать каталог DL_DIR за пределами каталога сборки, это позволит при необходимости удалить каталог сборки, сохранив загруженные из сети исходные файлы.

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

4.3.3.1. Выпуски исходных проектов

Выпуски исходных проектов, хранящиеся где-либо в виде архивов (например, tarball или zip). Эти файлы соответствуют отдельным заданиям. Например, на рисунке выше представлены выпуски для BusyBox, Qt и Dbus. Архив может содержать любую программу, которая может быть собрана с использованием задания.

4.3.3.2. Локальные проекты

Локальные проекты предоставляются пользователем и размещаются локально, возможно в каталоге, где пользователь проверяет элементы (например, каталог, с деревом исходных файлов, используемым группой разработки). Каноническим методом включения локальных проектов является использование класса externalsrc. Можно использовать файл local.conf или файл дополнения задания для переопределения или установке в задании каталога с файлами локального проекта.

4.3.3.3. Работа с SCM

Еще одним вариантом получения системой сборки исходных кодов является применение сборщиков (fetcher), работающих с системами SCM, такими как Git или Subversion, которые клонируют или выбирают (checked out) репозиторий. Задача do_fetch в BitBake использует переменную SRC_URI и префикс аргумента для определения конкретного сборщика. Система сборки OE может создавать архивы для репозиториев Git и помещать их в каталог DL_DIR, как описано в разделе BB_GENERATE_MIRROR_TARBALLS [3]. При извлечении из репозиториев BitBake применяет переменную SRCREV для определения конкретного выпуска.

4.3.3.4. Зеркала исходного кода

Поддерживаются два типа зеркал — предварительные и обычные, на которые указывают переменные PREMIRRORS и MIRRORS. соответственно. BitBake просматривает предварительные зеркала до поиска восходящих источников. Такие зеркала удобны при наличии общего каталога, который не указан в переменной DL_DIR (обычно это общий каталог внутри организации). Обычным зеркалом может быть любой сайт в Internet, служащий дополнительным местом размещения исходного кода и используемый при недоступности основного источника.

4.3.4. Хранилища пакетов

При генерации системой сборки образа или SDK, она берет пакеты из хранилища в каталоге сборки.

Хранилище содержит промежуточные результаты сборки. Система сборки OE включает классы для создания разных типов пакетов и нужно указать нужный класс в переменной PACKAGE_CLASSES. Перед размещением пакетов в хранилище система сборки проверяет качество полученного вывода с использованием класса insane.

Хранилище пакетов размещается в каталоге сборки, который задается комбинацией переменных и применяемым менеджером пакетов.

DEPLOY_DIR задается как tmp/deploy в каталоге сборки.
DEPLOY_DIR_* зависят от используемого менеджера пакетов. Для пакетов RPM, IPK, DEB или архивов используются переменные DEPLOY_DIR_RPM, DEPLOY_DIR_IPK, DEPLOY_DIR_DEB, DEPLOY_DIR_TAR.
PACKAGE_ARCH определяет зависимые от архитектуры подкаталоги. Например, пакет может создаваться для архитектуры i586 или qemux86.

BitBake применяет задачи do_package_write_* для создания пакетов и размещения их в хранилище (например, do_package_write_ipk для IPK). Описания задач приведены в разделах do_package_write_deb, do_package_write_ipk, do_package_write_rpm и do_package_write_tar [3]. Например, при использовании менеджера IPK и создании пакетов для архитектуры i586 и qemux86 пакеты будут размещены в build/tmp/deploy/ipk/i586 и build/tmp/deploy/ipk/qemux86.

4.3.5. BitBake

Система сборки OE применяет BitBake для создания образов и SDK. Процесс работы BitBake включает несколько этапов, рассмотренных ниже. Документация BitBake представлена в [7].

4.3.5.1. Извлечение исходных кодов

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

Задачи do_fetch и do_unpack извлекают исходные файлы и распаковывают их в каталоге сборки. Для каждого локального файла (например, file://) из переменной SRC_URI в задании система сборки OE берет контрольную сумму файла для задания и помещает ее в подпись для задачи do_fetch. Если локальный файл изменен, задача do_fetch и все зависящие от нее задачи запускаются заново.

По умолчанию все выполняется в каталоге сборки, имеющем определенную структуру, описанную в разделе build/ [3].

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

TMPDIR — базовый каталог, где система OE выполняет всю сборку (по умолчанию каталог tmp).
PACKAGE_ARCH — архитектура для сборки пакетов, которая может зависеть от конечной цели (например, архитектуры машины, хоста сборки, SDK или конкретной машины).
TARGET_OS — операционная система целевого устройства (обычно linux, например qemux86-poky-linux»).
PN — имя задания для сборки пакета (в ином контексте смысл переменной может меняться).
WORKDIR — место, где система OE собирает задание (т. е. выполняет работу по созданию пакета).
- PV — версия задания, используемая для сборки пакета.
- PR — выпуск (revision) задания, используемый для сборки пакета.
S — каталог с распакованными исходными файлами для задания.
- BPN — имя задания для сборки пакета (вариант переменной PN без общих префиксов и суффиксов).
- PV — версия задания, используемая для сборки пакета.

Следует отметить на приведенном выше рисунке две иерархии — на основе архитекуты пакета (PACKAGE_ARCH) и машины (MACHINE). Нижележащие структуры идентичны. Различие будет определяться тем, что машина OE считает целью сборки (например, общая архитектура, хост сборки, SDK или конкретная машина).

4.3.5.2. Применение правок

После извлечения и распаковки исходногог кода BitBake находит patch-файлы и применяет их к источникам.

Задача do_patch использует операторы SRC_URI в задании и переменную FILESPATH для поиска patch-файлов. По умолчанию предполагается, что такие файлы имеют расширение .patch или .diff, но можно использовать параметры SRC_URI для указания системе сборки иных способов поиска patch-файлов. BitBake находит и применяет файлы правок для одного задания в порядке их указания. Переменная FILESPATH задает принятый по умолчанию набор каталогов для поиска patch-файлов. Найденные файлы применяются к исходным файлам из каталога S.

Размещение исходных файлов описано в параграфе 4.3.5.1. Извлечение исходных кодов, создание и применение patch-файлов описано в разделе Patching Code [1]. Дополнительная информация содержится в разделе Use devtool modify to Modify the Source of an Existing Component [2] и Using Traditional Kernel Development to Patch the Kernel [9].

4.3.5.3. Настройка, компиляции и подготовка пакетов

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

Эта часть процесса сборки включает несколько этапов.

Задача do_prepare_recipe_sysroot организует до 2 каталогов sysroot (recipe-sysroot и recipe-sysroot-native) в ${WORKDIR}, чтобы на этапе создания пакетов в sysroots могло быть содержимое задач do_populate_sysroot заданий, от которых зависит данное задание. Каталоги sysroot имеются для естественных (работают на хосте сборки) и целевых двоичных файлов.
Задача do_configure настраивает конфигурацию исходного кода, включая и отключая соответствующие опции для собираемой программы. Настройка конфигурации может определяться самим заданием или унаследованным классом. Кроме того, конфигурацию может настраивать сама программа в зависимости от цели сборки. Конфигурации, обслуживаемые задачей do_configure относятся к исходному коду, собираемому заданием. При использовании класса autotools можно добавить опции с помощью переменных EXTRA_OECONF и PACKAGECONFIG_CONFARGS.
Задача do_compile запускается после настройки конфигурации и выполняется в каталоге, заданном переменной B, который по умолчанию содержит каталог, указываемый переменной S.
Задача do_install выполняется по завершении компиляции и копирует файлы из каталога B в область хранения, указанную переменной D, где позднее выполняется создание пакетов.

4.3.5.4. Разделение пакетов

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

Задачи do_package и do_packagedata совместно анализируют файлы в каталоге D и делят их на группы в соответствии с доступными пакетами и файлами. Анализ включает исключение символов отладки, поиск зависимостей от общих библиотек и связи между пакетами. Задача do_packagedata на основе анализа создает метаданные пакета, по которым система сборки генерирует пакеты. Задача do_populate_sysroot копирует нужную часть файлов, установленных задачей do_install, в нужный каталог sysroot. Для рабочих и промежуточных результатов анализа и разделения пакетов применяется несколько областей.

PKGD - целевой каталог (package) для пакетов до их разделения.
PKGDESTWORK — временная область (pkgdata), используемая задачей do_package для хранения метаданных.
PKGDEST - родительский каталог (packages-split) для пакетов после разделения.
PKGDATA_DIR — общий каталог глобального состояния, куда записываются метаданные, создаваемые процессом генерации пакетов. Процесс создания пакета копирует метаданные из PKGDESTWORK в каталог PKGDATA_DIR, где они становятся доступными глобально.
STAGING_DIR_HOST - путь к sysroot для системы, на которой компонента будет работать (recipe-sysroot).
STAGING_DIR_NATIVE - путьк sysroot с компонентами для сборочного хоста (recipe-sysroot-native).
STAGING_DIR_TARGET - путь к sysroot с компонентами, собранными для выполнения в системе и генерирующими код для другой машины(например, задания cross-canadian).

Переменная FILES задает файлы, входящие в каждый пакет из PACKAGES.

В зависимости от типа создаваемых пакетов (RPM, DEB, IPK) задача do_package_write_* создает реальные пакеты и помещает их в хранилище ${TMPDIR}/deploy (см. параграф 4.3.4. Хранилища пакетов). Поддержки создания хранилищ непосредственно из каталогов deploy/* нет, поскольку для этого обычно требуется некий механизм загрузки новых пакетов в официальные хранилища (например, дистрибутив Ångström).

4.3.5.5. Создание образа

После разделения пакетов и записи их в хранилища (Package Feed) система сборки использует BitBake для создания образа файловой системы.

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

IMAGE_INSTALL - список базового набора пакетов для установки из хранилища (Package Feeds).
PACKAGE_EXCLUDE — пакеты, которые не следует устанавливать в образ.
IMAGE_FEATURES — свойства для включения в образ, большинство которых отображается в пакеты.
PACKAGE_CLASSES указывает используемый менеджер пакетов (RPM, DEB, IPK), а затем помогает определить местонахождение пакетов в хранилище.
IMAGE_LINGUAS определяет языки для которых устанавливаются дополнительные пакеты поддержки.
PACKAGE_INSTALL задает окончательный список пакетов, передаваемый менеджеру для установки в образ.

Корневая файловая система создается с переменной IMAGE_ROOTFS, указывающей ее местоположение, и переменной PACKAGE_INSTALL со списком пакетов для установки. инсталляция пакетов выполняется под управлением менеджера пакетов (dnf/rpm, opkg, apt/dpkg) независимо от того, включен ли менеджер для целевой платформы. В конце процесса, если менеджер пакетов не включен для целевой платформы, его файлы удаляются из корневой системы. На финальной стадии установки пакетов выполняются сценарии пост-установки. Все сценарии, которые не удалось выполнить на сборочном хосте, будут запущены при первой загрузке на целевой платформе. Если используется корневая файловая система с доступом только для чтения, все сценарии пост-установки должны быть выполнены на сборочном хосте в процессе инсталляции.

Пост-обработка выполняется на заключительных этапах задачи do_rootfs и включает оптимизацию и создание файла манифеста, который размещается в каталоге образа корневой файловой системы. В этом файле содержится построчный список установленных пакетов. Файл манифеста полезен, например, для класса testimage, чтобы решить вопрос о запуске соответствующих тестов. Процесс оптимизации запускается на созданном образе и включает mklibs, prelink и другие команды пост-обработки, в соответствии с переменной ROOTFS_POSTPROCESS_COMMAND. Процесс mklibs оптимизирует размер библиотек, а prelink — динамические ссылки общих библиотек для оптимизации времени загрузки исполняемых файлов.

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

Система сборки при необходимости динамически создает задачи do_image_* в соответствии с типами образов в переменной IMAGE_FSTYPES. Процесс превращает все в файл образа или устанавливает файлы образа и может сжимать образ корневой файловой системы. Форматы корневой файловой системы зависит от переменной IMAGE_FSTYPES, а сжатие зависит от его поддержки файловой системой. Например, динамически создаваемая задача при построении определенного типа образа может иметь вид do_image_type. Если в IMAGE_FSTYPES указан тип ext4, динамически создаваемая задача будет иметь форму do_image_ext4.

Финалом создания образа является задача do_image_complete, которая выполняет пост-обработку образа в соответствии с переменной IMAGE_POSTPROCESS_COMMAND, которая содержит список функций, вызываемых однократно при создании системой сборки окончательных файлов образа. Весь процесс генерации образа выполняется в рамках Pseudo, что позволяет задать корректных владельцев файлов корневой файловой системы.

4.3.5.6. Создание SDK

Система сборки OE использует BitBake для генерации сценариев установки SDK как для стандартных, так и для расширяемых SDK (eSDK).

Создание SDK описано в разделе 4.4. Создание инструментов кросс-разработки, а преимущества сборки с помощью задачи do_populate_sdk рассмотрены в разделе Building an SDK Installer [2].

Подобно созданию образа, сценарий установки SDK состоит из нескольких этапов и зависит от множества переменных. Задачи do_populate_sdk и do_populate_sdk_ext используют эти переменные для оказания помощи при создании списка реально устанавливаемых пакетов (см. параграф 4.3.7. SDK для разработки приложений). Задача do_populate_sdk помогает создать стандартный SDK и обрабатывает целевую и хостовую часть. Целевая часть включает библиотеки и заголовочные файлы, а хостовая — SDK, работающий на SDKMACHINE. Задача do_populate_sdk_ext помогает собрать eSDK и обрабатывает хостовуб и целевую части иначе, чем для стандартных SDK, инкапсулируя систему сборки, включающую все, что требуется для SDK (на хосте и целевой платформе). Независимо от типа SDK, задачи выполняют некоторую очистку, после чего создается сценарий организации среды кросс-разработки и все требуемые файлы конфигурации. Финальным выводом является сценарий установки инструментов кросс-разработки (.sh), включающий сценарий организации среды.

4.3.5.7. Файлы штампов и повторный запуск задач

Для каждой выполненной задачи BitBake записывает файл штампа в каталог STAMPS_DIR. Начало имени файла задает переменная STAMP, а остальная часть включает имя задачи и текущую входную контрольную сумму (4.5.2. Контрольные суммы (подписи)). Эта схема именования предполагает BB_SIGNATURE_HANDLER = «OEBasicHash», что выполняется почти всегда в текущей версии OE.

Для решения вопроса о повторном запуске задачи BitBake проверяет наличие для задачи штампа с совпадающей контрольной суммой. При наличии такого файла предполагается, что вывод задачи имеется и пригоден. Если такого файла нет, задача запускается снова. Механизм штампов является более общим, чем механизм кэширования общего состояния (sstate), описанный в параграфе 4.3.5.8. Пропуск задач и общее состояние. BitBake избегает повтора задач с действительным штампом в дополнение к задачам, которые можно ускорить с помощью кэша sstate. Однако следует понимать, что файлы штампов служат лишь маркерами проделанной работы и не содержат вывода задач. Реальный вывод размещается где-либо в TMPDIR (например, в WORKDIR задания). Механизм кэширования sstate добавляет способ кэширования вывода задач, который может совместно использоваться разными машинами сборки. Поскольку STAMPS_DIR обычно размещается в каталоге TMPDIR, удаление этого каталога приведет к удалению STAMPS_DIR и задачи будут запускаться повторно для нового заполнения TMPDIR.

Если нужно признать ту или иную задачу устаревшей, можно пометить ее флагом переменной nostamp. Если какая-либо задача зависит от такой задачи, она тоже будет считаться устаревшей (возможно, это не то, что вы хотите). Дополнительные сведения о подписях задач даны в разделе Viewing Task Variable Dependencies [1].

4.3.5.8. Пропуск задач и общее состояние

Приведенные выше описания задач предполагали, что BitBake нужно собирать все и нет созданного ранее вывода. В реальности BitBake позволяет пропустить задачи, если имеются созданные ранее объекты, которые обычно доступны в форме кэша общего состояния (sstate).

Идея задачи do_taskname_setscene заключается в том, что можно пропустить ту или иную задачу и просто поместить в нужное место соответствующие файлы, которые уже созданы. В некоторых случаях (например, для задач do_package_write_*) это имеет смысл, но в других задачах (например, do_patch или do_unpack) бесполезно, поскольку объем выполняемой работы не снижается.

В системе сборки варианты пропуска (setscene) доступны чаще всего для задач do_package, do_package_write_*, do_deploy, do_packagedata и do_populate_sysroot, которые создают основную часть вывода системы сборки. Зависимости между задачами и их предшественниками известны системе сборки. Например, если BitBake запускает do_populate_sysroot_setscene для чего-либо, не имеет смысла выполнять любую из задач do_fetch, do_unpack, do_patch, do_configure, do_compile, do_install. Однако при необходимости выполнения do_package BitBake придется запускать и другие задачи. Ситуация усложняется при использовании кэша sstate, поскольку некоторые объекты просто не нужны. Например, может не требоваться компилятор или естественные инструменты, такие как quilt, если нечего компилировать или исправлять (patch). Если пакеты do_package_write_* доступны в sstate, BitBake не нужны данные задачи do_package.

С учетом приведенных сложностей BitBake работает в двух фазах. Сначала выполняется этап подготовки, где BitBake проверяет кэш sstate для всех целей, которые планируется собрать. BitBake выполняет быструю проверку наличия объектов без их загрузки. Если ничего не найдено, выполняется обычный процесс сборки. При наличии объекта в sstate система сборки работает в обратном направлении, от конечных целей, заданных пользователем. Например, при сборке образа система сначала ищет пакеты, нужные для создания образа. Если эти пакеты доступны, компилятор не требуется и даже не будет загружаться. Если что-то оказалось недоступным или возник отказ при загрузке или в задаче setscene, система сборки пытается установить зависимости (такие как компилятор) из кэша.

Доступность объектов кэша sstate определяется функцией, которая указана переменной BB_HASHCHECK_FUNCTION и возвращает список доступных объектов. Функция, указанная в BB_SETSCENE_DEPVALID, определяет необходимость выполнения данной зависимости.

4.3.6. Образы

Создаваемые системой сборки образы представляют собой сжатую форму корневой файловой системы, пригодной к загрузке на целевой платформе. Процесс создания образа показан на рисунке. Примеры образов, предоставляемых YP приведены в разделе Images [3].

Образы записываются в каталог tmp/deploy/images/machine/ внутри каталога сборки. Здесь размещаются все файлы, предназначенные для загрузки на целевом устройстве. Переменная DEPLOY_DIR указывает каталог развертывания, а DEPLOY_DIR_IMAGE — каталог с образами для текущей конфигурации.

Kernel-image — двоичный файл ядра. Переменная KERNEL_IMAGETYPE определяет схему именования файлов с образами ядра. В каталоге deploy/images/machine может храниться множество образов ядра для машины.
Root-filesystem-image — корневая файловая система для целевого устройства (например, файлы *.ext3 или *.bz2). Тип файловой системы задает переменная IMAGE_FSTYPES. В каталоге deploy/images/machine может храниться множество образов корневой файловой системы для машины.
Kernel-modules — архив модулей для ядра, создание которого можно отключить установкой MODULE_TARBALL_DEPLOY = «0». В каталоге deploy/images/machine может храниться множествоархивов модулей ядра для машины.
bootloaders — загрузчики, поддерживающие образ, если целевая платформа позволяет это. В каталоге deploy/images/machine может храниться множество загрузчиков для машины.
symlinks — каталог deploy/images/machine содержит символьные ссылки, указывающие наиболее свежие файлы для каждой машины. Ссылки могут быть полезны для внешних сценариев.

4.3.7. SDK для разработки приложений

Процессы создания SDK различаются для стандартного (например, bitbake -c populate_sdk imagename) и расширяемого SDK (например, bitbake -c populate_sdk_ext imagename).

Вывод представляет собой набор файлов, включающий самораспаковывающийся установщик SDK (*.sh), манифесты для хоста и цели, а также файлы для тестирования SDK. Пакет SDK включает инструменты кросс-разработки, набор библиотек и заголовочных файлов, а также сценарий организации среды SDK. Инструменты можно считать хостовой частью SDK, поскольку они применяются на машине разработки. Библиотеки и заголовки можно считать целевой частью, поскольку они собираются для целевой машины. Сценарий инициализации среды позволяет организовать рабочее окружение SDK.

YP поддерживает несколько методов организации среды кросс-разработки, включая загрузку собранного установщика SDK и сборку и инсталляцию своего SDK. Базовые сведения о кросс-разработке в среде YP приведены в разделе 4.4. Создание инструментов кросс-разработки, а организации среды рассмотрена в [2].

Выходные файлы для SDK сохраняются в каталоге deploy/sdk внутри каталога сборки, как показано на рисунке выше. Для расширяемого SDK перечисленные ниже переменные помогают настроить процесс.

DEPLOY_DIRуказывает каталог развертывания (deploy).

SDK_EXT_TYPE управляет копированием элементов общего состояния в расширяемый SDK (по умолчанию копируются).
SDK_INCLUDE_PKGDATA управляет включением packagedata в расширяемый SDK для заданий цели world.
SDK_INCLUDE_TOOLCHAIN управляет включением инструментария в расширяемый SDK.
SDK_LOCAL_CONF_WHITELIST — список переменных для переноса из среды сборки в расширяемый SDK.
SDK_LOCAL_CONF_BLACKLIST — список переменных, не переносимых из среды сборки в расширяемый SDK.
SDK_INHERIT_BLACKLIST — список классов для глобального удаления из INHERIT в расширяемом SDK.

Приведенные ниже переменные связаны со стандартным SDK.

DEPLOY_DIR указывает каталог развертывания (deploy).
SDKMACHINE — архитектура машины, где будут работать инструменты кросс-разработки.
SDKIMAGE_FEATURES — список свойств для включения в целевую (target) часть SDK.
TOOLCHAIN_HOST_TASK — список пакетов для хостовой части SDK (работают на SDKMACHINE). При использовании bitbake -c populate_sdk imagename для создания SDK применяется заданный по умолчанию набор, который можно изменить в этой переменной.
TOOLCHAIN_TARGET_TASK — список пакетов для целевой части SDK (работают на целевой платформе).
SDKPATH задает путь установки SDK, предлагаемый сценарием инсталляции.
SDK_HOST_MANIFEST — список установленных пакетов хостовой части SDK.
SDK_TARGET_MANIFEST — список установленных пакетов целевой части SDK.

4.4. Создание инструментов кросс-разработки

YP самостоятельно выполняет большую часть работы по созданию инструментов кросс-разработки. В этом разделе кратко описано создание и использование инструментов, а более полные сведения содержатся в [2].

В среде YP инструменты кросс-разработки служат для сборки образов и приложений, предназначенных для работы на целевой платформе. Система сборки OE создает нужные инструменты с помощью нескольких команд. На рисунке показан общий вид среды сборки и использования инструментария.

Большая часть работы выполняется на хосте сборки, используемом для создания образов и обычно работающем в среде YP. При запуске BitBake для создания образа система сборки OE использует компилятор gcc на хосте для создания кросс-компилятора gcc-cross, который применяется BitBake для компиляции исходных файлов при создании целевого образа. Можно считать gcc-cross автоматически генерируемым кросс-компилятором, который применяется только в BitBake. Расширяемый SDK не применяет gcc-cross-canadian, поскольку этот SDK содержит копию среды сборки OE и файловую систему sysroot с gcc-cross.

Цепочка событий при создании gcc-cross имеет вид

gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime

gcc — компилятор GNU Compiler Collection (GCC) на сборочном хосте.
binutils-cross — минимальный набор двоичных утилит, требуемых для запуска фазы gcc-cross-initial.
gcc-cross-initial — ранняя стадия процесса создания кросс-компилятора. На этом этапе создается gcc-cross, библиотека C и другие компоненты, требуемые для сборки на последующих этапах финального кросс-компилятора. Этот инструмент является естественным (native) пакетом (для хоста сборки).
linux-libc-headers — заголовочные файлы, нужные кросс-компилятору.
glibc-initial — изначальная версия библиотеки Embedded GNU C (GLIBC), нужная для создания glibc.
glibc — библиотека GNU C.
gcc-cross — финальная стадия процесса создания кросс-компилятора, который BitBake использует при сборке образа для целевого устройства.
При замене инструментов кросс-компиляции потребуется заменить и gcc-cross. Этот инструмент также является естественным пакетом (работает на хосте сборки).
gcc-runtime — используемые при работе (runtime) библиотеки из процесса созданния инструментов. Этот инструмент создает двоичный файл с runtime-библиотеками для целевого устройства.

Можно с помощью системы сборки OE создать установщик переносимого SDK для разработки приложений. При запуске установщика будет инсталлироваться инструментарий (например, gcc-cross-canadian, binutils-cross-canadian, и другие инструменты nativesdk-*), который является естественным для SDK (т. е. для SDK_ARCH), и нужно собирать и тестировать программы. На рисунке выше показаны команды, позволяющие собрать эти инструменты. Эти средства кросс-разработки собираются для работы на SDKMACHINE, которая может, но не обязана быть хостом сборки.

Если целевая архитектура поддерживается YP, можно воспользоваться готовыми образами из комплекта YP, где уже включены установщики инструментов кросс-разработки.

Процесс создания переносимого инструментария имеет вид

gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian

gcc — компилятор GNU Compiler Collection (GCC) на сборочном хосте.
binutils-crosssdk — минимальныйнабор двоичных утилит, требуемых для запуска фазы gcc-crosssdk-initial.
gcc-cross-initial — ранняя стадия процесса создания кросс-компилятора. На этом этапе создается gcc-cross, библиотека C и другие компоненты, требуемые для сборки на последующих этапах финального кросс-компилятора. Этот инструмент является естественным (native) пакетом (для хоста сборки).
linux-libc-headers — заголовочные файлы, нужные кросс-компилятору.
glibc-initial — изначальная версия библиотеки Embedded GNU C (GLIBC), нужна для создания nativesdk-glibc.
nativesdk-glibc — библиотека Embedded GLIBC, нужная для создания gcc-crosssdk.
gcc-crosssdk — финальный этап процесса создания переносимого кросс-компилятора, который является временным и не покидает сборочный хост. /тот компилятор помогает создать компилятор gcc-cross-canadian compiler, который можно переносить. Этот инструмент является естественным пакетом (на хосте сборки).
gcc-cross-canadian — окончательный переносимый кросс-компилятор. При работе на SDKMACHINE этот инструмент создает исполняемый код для целевого устройства. Создается лишь один компилятор cross-canadian для архитектуры, поскольку эти компиляторы могут выполнять оптимизацию для разных процессоров с использованием конфигурации, передаваемой компилятору в командах. Это позволяет обойтись одним компилятором и снижает размер инструментария.

Информация о сборке установщика инструментов кросс-разработки приведена в разделе Building an SDK Installer [2].

4.5. Общий кэш состояний

Система сборки OE создает все с нуля, если только BitBake не указывает, что некоторые части не нужно собирать заново. Создание с нуля привлекательно, поскольку все собранные компоненты будут свежими и не останется устаревших данных, которые могут вызвать проблемы. Обычно разработчики при обнаружении проблем начинают сборку с «чистого листа», чтобы знать исходное состояние. Однако сборка с нуля кроме преимуществ имеет и недостатки, связанные с существенным расходом времени на сборку.

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

Какая часть системы была изменена, а что сохранилось неизменным?
Были измененные части удалены или заменены?
Как будут использоваться собранные ранее неизменные компоненты, если они доступны?

По первому вопросу система сборки находит изменения на «входах» в данную задачу через контрольные суммы (подписи) ввода. Если подпись изменилась, система считает входные данные измененными с необходимостью повтора задачи. По второму вопросу код общего состояния (sstate) отслеживает вывод задач в процессе сборки, который может быть удален или обновлен. Третий вопрос частично решается вместе со вторым в предположении, что система сборки может извлекать объекты sstate из удаленного хранилища и устанавливать пригодные объекты.

Система сборки не поддерживает информацию PR как часть общего состояния пакетов, поэтому существуют соображения, влияющие на поддержку подачи общего состояния. Информация о работе системы сборки с пакетами и возможности отслеживания роста PR приведена в разделе Automatically Incrementing a Binary Package Revision Number [1].
Код поддержки инкрементной сборки достаточно сложен. Методы, помогающие обойти проблемы, связанные с кодом общего состояния, рассмотрены в разделах Viewing Metadata Used to Create the Input Signature of a Shared State Task и Invalidating Shared State to Force a Task to Run [1].

4.5.1. Общая архитектура

При определении частей, требующих повторной сборки, BitBake работает на уровне задач, а не заданий. Для разъяснения такого подхода рассмотрим ситуацию, когда был включен менеджер пакетов IPK, а затем произошел переход на DEB. В этом случае вывод задач do_install и do_package остается пригодным, однако при работе на уровне заданий сборка не будет включать файлов .deb и придется повторить ее целиком, что не является эффективным решением.

4.5.2. Контрольные суммы (подписи)

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

Однако в реальности задача сложнее, поскольку в контрольную сумму следует включать не все. Например, реальный путь сборки WORKDIR не имеет значения и изменение каталога не должно влиять на вывод для целевых пакетов. Кроме того, процесс сборки может создавать переносимые естественные и кросс-пакеты. Оба варианта пакетов запускаются на хосте сборки, однако вывод кросс-пакетов предназначен для целевой архитектуры. Поэтому из контрольной суммы следует исключить WORKDIR. Проще всего это сделать, задав для WORKDIR некое фиксированное значение, и создавать контрольную сумму для сценария run.

Другая проблема заключается в том, что сценарий run содержит функции, которые могут не вызываться. Решение для инкрементной сборки включает код, вычисляющий зависимости между shell-функциями. Этот код служит для сокращения сценариев run до минимального набора, смягчая проблему и делая сценарии run более читаемыми.

Для сценариев Python применяется такой же подход даже в более сложных задачах. Процесс должен выяснить, к каким переменным обращается функция Python и зависимости между функциями, а затем создавать контрольную сумму для входных данных задачи. Подобно WORKDIR, существуют ситуации, где зависимости следует игнорировать. Это можно задать с помощью строки вида PACKAGE_ARCHS[vardepsexclude] = «MACHINE». Здесь предполагается, что переменная PACKAGE_ARCHS не зависит от значения MACHINE даже при наличии ссылки на нее. Точно также имеются случаи, когда нужно добавить зависимости, которые BitBake не может найти. Это можно сделать в форме строки PACKAGE_ARCHS[vardeps] = «MACHINE», которая явно указывает зависимость PACKAGE_ARCHS от MACHINE.

Возможен случай с Python, где BitBake не может определить зависимости. При работе в режиме отладки (-DDD), BitBake выдает сообщения при обнаружении невозможности выяснить зависимости. Команда YP пока не нашла решения этой проблемы, но занимается его поиском.

До этого рассматривался лишь прямой ввод в задачи. Вводимая таким образом информация в коде называется базовым хэшем (basehash). Однако остается косвенный ввод — элементы, которые уже собраны и имеются в каталоге сборки. Контрольная сумма (подпись) для конкретной задачи должна учитывать хэш-значения всех задач, от которых она зависит. Выбор зависимостей для добавления задает политика и в результате создается основная контрольная сумма, объединяющая basehash и хэш-значения всех задач, от которых имеются зависимости.

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

     BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
         SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
         USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
         PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
         CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"

В примере не указана переменная WORKDIR, поскольку она задает путь внутри TMPDIR, уже имеющейся в списке.

Правила включения хэш-значений с учетом цепочек зависимостей являются более сложными и обычно реализуются функциями Python. Код в файле meta/lib/oe/sstatesig.py содержит два примера т показывает, как можно включить свои правила в систему. Этот файл определяет два базовых генератора подписей, используемых в OE-Core, — OEBasic и OEBasicHash. По умолчанию в BitBake включен фиктивный обработчик подписей noop. Это означает, что поведение не отличается от предыдущих версий. OE-Core использует по умолчанию обработчик OEBasicHash (файл bitbake.conf)

     BB_SIGNATURE_HANDLER ?= "OEBasicHash"

OEBasicHash в отличие от OEBasic добавляет хэш задачи в файлы штампов. Это ведет к тому, что любое изменение метаданных, влияющее на хэш задачи, автоматически вызывает повторный запуск задачи. В результате не нужно увеличивать значения PR, а изменения метаданных автоматически распространяются по сборке.

Следует отметить, что конечным результатом генерации подписей является доступность в сборке некоторых данных о зависимостях и хэш-значениях, включая:

BB_BASEHASH_task-taskname — базовые хэш-значения для каждой задачи в задании;
BB_BASEHASH_filename:taskname — базовыехэш-значения для каждой зависимой задачи;
BBHASHDEPS_filename:taskname — зависимости для каждой задачи;
BB_TASKHASH — хэш текущей работающей задачи.

4.5.3. Общее состояние

Контрольные суммы и зависимости решают проблему поддержки общего состояния наполовину. Другая половина связана с возможностью использовать данные контрольной суммы в процессе сборки для повторного использования или повторной сборки конкретных компонент. Класс sstate является сравнительно общей реализацией создания «моментального снимка» данной задачи. Идея состоит в том, чтобы процесс сборки мог не думать об источнике вывода задачи. Это могут быть недавно собранные файлы или файлы, загруженные извне и распакованные. Имеется два типа вывода, один из которых является созданием каталога в WORKDIR. Примером может служить вывод задачи do_install или do_package. Другой тип связан с объединением вывода в общем дереве каталогов, таком как sysroot.

Команда YP пыталась сохранить детали реализации спрятанными в классе sstate. С точки зрения пользователя добавление переноса спрятанного общего состояния в задачу так же просто, как в примере do_deploy из класса.

     DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
     SSTATETASKS += "do_deploy"
     do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
     do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"

     python do_deploy_setscene () {
         sstate_setscene(d)
     }
     addtask do_deploy_setscene
     do_deploy[dirs] = "${DEPLOYDIR} ${B}"
     do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"

Ниже приведены разъяснения к примеру.

Добавление do_deploy к SSTATETASKS вносит требование дополнительной обработки, связанной с sstate, которая реализуется в классе sstate до задачи do_deploy или после нее.
Назначение do_deploy[sstate-inputdirs] = «${DEPLOYDIR}» указывает, что do_deploy при обычной работе (без кэша sstate) помещает свой вывод в ${DEPLOYDIR} и он становится вводом кэша общего состояния.
Строка do_deploy[sstate-outputdirs] = «${DEPLOY_DIR_IMAGE}» ведет к копирования содержимого кэша общего состояния в ${DEPLOY_DIR_IMAGE}.

Если do_deploy еще нет в кэше общего состояния или входная контрольная сумма (подпись) изменилась с момента кэширования вывода, запускается задача для заполнения кэша общего состояния, после чего содержимое кэша копируется в ${DEPLOY_DIR_IMAGE}. Если do_deploy есть в кэше и контрольная сумма действительна (вводы имеющих отношение к делу задач не изменились), содержимое кэша напрямую копируется в ${DEPLOY_DIR_IMAGE} задачей do_deploy_setscene task с пропуском задачи do_deploy.
Приведенная ниже задача обеспечивает логику склейки для предыдущих установок.
```
     python do_deploy_setscene () {
         sstate_setscene(d)
     }
     addtask do_deploy_setscene
```
Задача sstate_setscene() принимает указанные выше флаги как входные данные и ускоряет do_deploy за счет кэша состояний, если это возможно. Если ускорение удалось, sstate_setscene() возвращает True. В противном случае возвращается False и выполняется обычная задача do_deploy. Дополнительная информация приведена в разделе setscene [7].
Строка do_deploy[dirs] = «${DEPLOYDIR} ${B}» создает ${DEPLOYDIR} и ${B} до запуска задачи do_deploy, а также устанавливает ${B} в качестве рабочего каталога do_deploy. Дополнительная информация приведена в разделе Variable Flags [7].

Если sstate-inputdirs и sstate-outputdirs совпадают, можно использовать sstate-plaindirs. Например, для сохранения вывода ${PKGD} и ${PKGDEST} из задачи do_package можно использовать
```
     do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
```
Строка do_deploy[stamp-extra-info] = «${MACHINE_ARCH}» добавляет метаданные в файл штампа. В этом случае метаданные делают задачу специфичной для архитектуры машины. Описание флага stamp-extra-info приведено в разделе [7].
Переменные sstate-inputdirs и sstate-outputdirs могут включать несколько каталогов. Например, переменные PKGDESTWORK и SHLIBWORK объявлены ниже как входные для общего состояния, а PKGDATA_DIR и SHLIBSDIR — как соответствующие выходные каталоги.
```
     do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
     do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
```
Эти методы также позволяют взять файл блокировки при работе со структурами кэша общих состояний для случаев, когда важно добавление или удаление файлов
```
     do_package[sstate-lockfile] = "${PACKAGELOCK}"
```

Код общего состояния просматривает файлы состояний по переменным SSTATE_DIR и SSTATE_MIRRORS.

     SSTATE_MIRRORS ?= "\
     file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
     file://.* file:///some/local/dir/sstate/PATH"

Каталог общего состояния (SSTATE_DIR) содержит подкаталоги, имена которых образованы двумя первыми символами хэш-значения. Если структура каталога общего состояния для зеркала совпадает со структурой SSTATE_DIR, нужно задать «PATH» как часть URI, чтобы разрешить системе сборки сопоставление с подходящим каталогом.

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

Процессы сборки применяют задачи *_setscene в фазе ускорения задач, которую BitBake проходит перед основным кодом, пытаясь ускорить все задачи, для которых можно найти общее состояние. Если такое состояние найдено, это позволяет пропустить задачу вместе с задачами, от которых она зависит.

4.6. Автоматически добавляемые зависимости при работе

Система сборки OE автоматически добавляет общие типы зависимостей между пакетами при работе, избавляя от необходимости включать их в RDEPENDS. Имеется три автоматических механизма (shlibdeps, pcdeps, depchains), которые обслуживают общие библиотеки, конфигурацию пакетов (pkg-config), а также пакеты разработки и отладки (-dev и -dbg). Остальные типы зависимостей должны указываться вручную.

shlibdeps. При выполнении задачи do_package для каждого задания отмечаются все общие библиотеки, устанавливаемые заданием. Для каждой такой библиотеки содержащий ее пакет регистрируется как поставщик библиотеки (soname ). Полученное сопоставление между пакетами и общими библиотеками (shared-library-to-package) сохраняется глобально в переменной PKGDATA_DIR задачей do_packagedata.

Одновременно все исполняемые файлы и библиотеки, устанавливаемые заданием, проверяются на предмет связи с общими библиотеками. Для каждой найденной зависимости проверяется PKGDATA_DIR для обнаружения присутствия пакетов (вероятно из других заданий), предоставляющих библиотеку. Если такой пакет найден, добавляется зависимость при работе от содержащего библиотеку пакета.

Автоматически добавляемые зависимости учитывают также ограничения по версиям. Это ограничение указывает, что должна применяться версия не ниже текущей версии пакета, предоставляющего библиотеку, как будто добавлено условие «package (>= version)» в RDEPENDS. Это заставляет при необходимости обновлять пакет, содержащий библиотеку.

Если нужно исключить регистрацию пакета в качестве поставщика общей библиотеки (например, библиотека предназначена лишь для внутреннего применения), следует добавить PRIVATE_LIBS в задание для пакета.
pcdeps. При выполнении задачи do_package для каждого задания фиксируются все модели pkg-config (*.pc), установленные заданием. Для каждого модуля содержащее его задание фиксируется как поставщик модуля. Полученное сопоставление (module-to-package) сохраняется в переменной PKGDATA_DIR задачей do_packagedata для глобального доступа.

Одновременно все устанавливаемые заданием модули pkg-config проверяются на предмет зависимости от других модулей pkg-config. Модуль считается зависимым от другого модуля, если он содержит строку «Requires:», указывающую другой модуль. Для каждой зависимости просматривается переменная PKGDATA_DIR для обнаружения пакетов, которые могут содержать модуль. При нахождении такого пакета добавляется зависимость во время работы от содержащего модуль пакета.

Механизм pcdeps чаще всего определяет зависимости между пакетами -dev.
depchains. Если пакет foo зависит от пакета bar, пакеты foo-dev и foo-dbg также зависят от bar-dev и bar-dbg, соответственно. Например, для -dev пакет bar-dev может предоставлять заголовки и символьные ссылки на общие библиотеки, требуемые foo-dev, что указывает на зависимость между этими пакетами. Зависимости, добавляемые depchains, имеют форму RRECOMMENDS.

По умолчанию foo-dev имеет также зависимость RDEPENDS от foo, поскольку принятое по умолчанию значение RDEPENDS_${PN}-dev (в bitbake.conf) включает «${PN}».

Для обеспечения непрерывности цепочек зависимостей пакеты -dev и -dbg всегда создаются по умолчанию, даже если результат будут пустым.

Задача do_package зависит от do_packagedata каждого задания в DEPENDS через декларацию [deptask], которая гарантирует, что требуемая информация о сопоставлениях зависимостей будет доступна при корректной установке DEPENDS.

4.7. Fakeroot и Pseudo

Некоторые задачи (например, do_install, do_package_write*, do_rootfs, do_image*) проще выполнить при наличии прав, которые обычно предоставляются пользователю root. Например, задаче do_install нужно задавать идентификаторы UID GID для файлов с произвольными значениями.

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

Возможность запуска задач в фиктивной среде root называют fakeroot от ключевого слова (флага переменной) BitBake, запрашивающего для задачи фиктивную среду root.

В системе сборки OE программа, реализующая fakeroot, называется Pseudo. Эта программа переопределяет системные вызовы, используя переменную окружения LD_PRELOAD, что создает иллюзию работы от имени root. Для отслеживания фиктивного владения и прав доступа к файлам в результате операций, требующих полномочий root, Pseudo использует базу данных SQLite 3, которая хранится в файлах ${WORKDIR}/pseudo/files.db для отдельных заданий. Хранение базы в файле, а не в памяти, обеспечивает сохранение данных между разными задачами и сборками, что недоступно при использовании fakeroot.

При добавлении задачи, работающей с теми же файлами и каталогами, что и задача fakeroot, ее также нужно запускать в режиме fakeroot. В противном случае задача не сможет выполнить операции, разрешенные только пользователю root, и не увидит принадлежности и прав доступа для файлов, установленных другими задачами. Нужно также добавить зависимость от virtual/fakeroot-native:do_populate_sysroot, как показано ниже.

       fakeroot do_mytask () {
           ...
       }
       do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"

Дополнительная информация приведена в описании переменных FAKEROOT* [7]. Базовые сведения о работе с Fakeroot и Pseudo даны в статье [8].

Литература

[1] Yocto Project Development Tasks Manual, http://www.yoctoproject.org/docs/3.0/dev-manual/dev-manual.html.

[2] Yocto Project Application Development and the Extensible Software Development Kit (eSDK), http://www.yoctoproject.org/docs/3.0/sdk-manual/sdk-manual.html.

[3] Yocto Project Reference Manual, http://www.yoctoproject.org/docs/3.0/ref-manual/ref-manual.html.

[4] Yocto Project Board Support Package (BSP) Developer’s Guide, http://www.yoctoproject.org/docs/3.0/bsp-guide/bsp-guide.html.

[5] Yocto Project Quick Build, http://www.yoctoproject.org/docs/3.0/brief-yoctoprojectqs/brief-yoctoprojectqs.html.

[6] Toaster User Manual, http://www.yoctoproject.org/docs/3.0/toaster-manual/toaster-manual.html.

[7] BitBake User Manual, https://www.yoctoproject.org/docs/3.0/bitbake-user-manual/bitbake-user-manual.html.

[8] Why Not Fakeroot?, https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot.

[9] Yocto Project Linux Kernel Development Manual, http://www.yoctoproject.org/docs/3.0/kernel-dev/kernel-dev.html.

[10] Pro Git, https://github.com/progit/progit2-ru/releases/download/2.1.22/progit_v2.1.22.pdf.

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Board Support Package — пакет поддержки платы.

2Quick EMUlator.

3CROss PlatformS.

4Extensible Software Development Kit — расширяемый комплект для разработки программ.

5Quality assurance — гарантии качества.

6Executable and linkable format — исполняемый и компонуемый формат.

7Copy-On-Write — копирование при записи.

8Open PacKaGe management — открытая система управления пакетами.

9Software Package Data Exchange — обмен данными о программных пакетах.

10Open Source Definition.

Рубрика: Linux | Комментарии отключены

Руководство пользователя BitBake

Опубликовано 14.12.2019 автором Nikolai Malykh

BitBake User Manual

PDF

Richard Purdie, Chris Larson, and Phil Blundell

BitBake Community <bitbake-devel@lists.openembedded.org>

This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by/2.5/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California 94041, USA.

Глава 1. Обзор

В этом документе описана программа BitBake с попыткой максимально абстрагироваться от систем, использующих BitBake, таких как OpenEmbedded (OE) и Yocto Project (YP). В некоторых случаях описание включает варианты и примеры использования с четким указанием контекста.

1.1. Введение

BitBake представляет собой машину выполнения задач, которая позволяет запускать задачи Python для эффективного выполнения в параллель при работе в контексте ограничений, связанных с зависимостями между задачами. Одно из основных приложений BitBake — система OE создает на этой основе сборки программных стеков Linux для встраиваемых систем с использованием ориентированного на задачи подхода.

В некоторых отношениях BitBake напоминает GNU Make, но имеет ряд существенных отличий.

BitBake выполняет задачи в соответствии с предоставленными метаданными, которые создают задачу. Метаданные хранятся в заданиях (.bb) и связанных с ними файлах дополнения (.bbappend), конфигурационных (.conf) и включаемых (.inc) файлах, а также в классах (.bbclass), и дают BitBake инструкции о том, какие задачи запускать и как задачи зависят одна от другой.
BitBake включает библиотеку сборщика для извлечения исходного кода из локальных хранилищ, систем управления SCS¹ или web-сайтов.
Инструкции для каждой единицы сборки (например, программы) называют заданиями (recipe) и они содержат всю информацию о сборке (зависимости, размещение источников,контрольные суммы, описание и т. п.).
BitBake поддерживает модель «клиент-сервер» и может использоваться из командной строки или как служба XML-RPC, предоставляя несколько разных пользовательских интерфейсов.

1.2. История и назначение

BitBake исходно был частью проекта OE и его прообразом послужила система управления пакетами Portage из Gentoo Linux. 7 декабря 2004 г. член команды OE Chris Larson разделил проект на две части:

BitBake в качестве машины исполнения задач;
OE в качестве набора метаданных, используемых BitBake

Сейчас BitBake служит основой проекта OE, используемого для сборки и поддержки таких дистрибутивов Linux как Angstrom Distribution, а также служащего инструментом сборки проектов Linux, таких как Yocto Project.

До появления BitBake ни один инструмент не соответствовал всем задачам создания дистрибутивов Linux для встраиваемых систем. В стандартных дистрибутивах Linux не хватало функциональности и ни одна из систем на основе Buildroot для встраиваемых платформ не обеспечивала требуемой расширяемости и поддержки.

Ниже перечислены некоторые важные исходные цели BitBake.

Поддержка кросс-компиляции.
Обработка зависимостей между пакетами (при сборке на целевой и сборочной системе, а также при работе).
Поддержка любого числа задач внутри пакета, включая выборку исходных кодов, их распаковку, применение правок (patch), настройка и т. п.
Независимость от дистрибутива Linux на системе сборки и целевой системе.
Независимость от архитектуры.
Поддержка разных сборочных и целевых систем (Cygwin, BSD и т. п.).
Самодостаточность без тесной интеграции в корневую файловую системы машины сборки.
Обработка условных метаданных для целевой архитектуры, операционной системы, дистрибутива и машины.
Простота инструментов для поддержки локальных метаданных и пакетов, с которыми можно работать.
Простота использования BitBake в совместной работе с разными проектами для их сборки.
Предоставление механизма наследования для использования пакетами общего набора метаданных.

С течением времени возникли дополнительные требования.

Обработка вариантов базового задания (например, native, sdk, multilib).
Разделение метаданных по уровням для расширения и возможности переопределения.
Возможность представления заданного набора входных переменных задачи контрольной суммой для ускорения сборки при наличии уже собранных компонент.

BitBake удовлетворяет всем исходным требованиям и многим расширениям. Гибкость и возможности всегда были приоритетом. BitBake поддерживает возможности расширения, встроенный код Python и выполнение любых задач.

1.3. Концепции

Программа BitBake написана на языке Python. На верхнем уровне BitBake интерпретирует метаданные, определяет задачи, которые нужно выполнить, и запускает их. Подобно GNU Make, BitBake контролирует сборку программ через файлы, которые называются заданиями (recipe).

BitBake расширяет возможности простых инструментов, таких как GNU Make, позволяя определять более сложные задачи, например, сборку полного дистрибутива Linux для встраиваемой системы.

1.3.1. Задания

Задания BitBake, хранящиеся в файлах .bb, служат базовыми метаданными, обеспечивая BitBake:

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

В контексте BitBake или использующей программу системы сборки файлы .bb считаются заданиями. Иногда задания называют пакетами, однако это не совсем корректно, поскольку одно задание может включать множество пакетов.

1.3.2. Файлы конфигурации

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

1.3.3. Классы

Файлы классов .bbclass содержат информацию, которая может совместно использоваться множеством файлов метаданных. Дерево источников BitBake в настоящее время содержит один файл метаданных классов base.bbclass в каталоге classes. Классы из base.bbclass включаются автоматически для всех заданий и классов и содержат определения стандартных базовых задач, таких как выборка, распаковка, настройка (по умолчанию пуст), компиляция (запускается при наличии Makefile), инсталляция (по умолчанию пуст) и подготовка пакетов (по умолчанию пуст). Эти задачи часто переопределяются или расширяются другими классами, созданными при разработке проектов.

1.3.4. Уровни

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

Для иллюстрации применения уровней рассмотрим конфигурацию для конкретной целевой машины. Этот тип настройки обычно выделяют в специальный уровень, называемый уровнем BSP². Настройки для машины следует изолировать от заданий и метаданных, поддерживающих, например, новую среду GUI. Однако важно понимать, что уровень BSP может включать машинозависимые дополнения для заданий GUI без вмешательства в этот уровень. Это делается с помощью файлов дополнения BitBake append (.bbappend).

1.3.5. Файлы дополнения

Файлы дополнения .bbappend расширяют и переопределяют информацию имеющегося файла задания. BitBake считает, что каждому файлу дополнения соответствует свое задание, имена дополнения и задания должны иметь общий корень и могут различаться лишь суффиксом (например, formfactor_0.0.bb и formfactor_0.0.bbappend).

Информация в файле дополнения расширяет или переопределяет содержимое соответствующего файла задания. В именах файлов дополнения можно применять шаблон %, позволяющий дополнять множество заданий сразу. Например, файл busybox_1.21.%.bbappend будет соответствовать заданиям busybox_1.21.x.bb разных версий.

     busybox_1.21.1.bb
     busybox_1.21.2.bb
     busybox_1.21.3.bb

Использование символа % ограничено размещением непосредственно перед суффиксом .bbappend. Если задание busybox обновить для busybox_1.3.0.bb, файл дополнения не будет ему соответствовать. Однако можно назвать файл busybox_1.%.bbappend и соответствие будет восстановлено. В более общем случае можно назвать файл busybox_%.bbappend для соответствия любым версиям задания.

1.4. Получение BitBake

Клонирование BitBake из репозитория Git является рекомендуемым методом установки BitBake. Это позволяет получить файлы исправлений, а также доступ к стабильным ветвям и ветви master. После клонирования BitBake следует использовать последнюю стабильную ветвь, поскольку ветвь master может включать не совсем стабильные изменения. Обычно следует выбирать версию BitBake, соответствующую применяемым метаданным, которые обычно совместимы с прошлыми версиями, но могут не соответствовать новым.

Для клонирования BitBake служит команда git clone git://git.openembedded.org/bitbake, которая создаст копию репозитория в локальном каталоге bitbake. Если нужно использовать иное имя каталога, его указывают в команде. Например, для размещения локального репозитория в каталоге bbdev следует использовать команду
```
     $ git clone git://git.openembedded.org/bitbake bbdev
```
Установка из дистрибутива не рекомендуется, поскольку в большинстве случаев она отстает по версии.
Конкретная версия BitBake, которую можно загрузить из репозитория, указав известную ветвь или выпуск BitBake. Ниже приведен пример загрузки из репозитория BitBake версии 1.17.0
```
     $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
     $ tar zxpvf bitbake-1.17.0.tar.gz
```
После распаковки архива файлы будут находиться в каталоге bitbake-1.17.0.
Использование BitBake из выбранной системы сборки. Вместо выбора и установки отдельных уровней можно установить целиком систему сборки, которая будет включать версию BitBake, протестированную в части совместимости с остальными компонентами.

1.5. Команда `bitbake`

Команда bitbake является основным интерфейсом BitBake. Здесь описан синтаксис команды и даны примеры.

1.5.1. Использование и синтаксис

Описание синтаксиса можно получить по команде

$ bitbake -h
Usage: bitbake [options] [recipename/target recipe:do_task ...]

Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
will provide the layer, BBFILES and other configuration information.

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-b BUILDFILE, --buildfile=BUILDFILE
Execute tasks from a specific .bb recipe directly.
WARNING: Does not handle any dependencies from other
recipes.
-k, --continue Continue as much as possible after an error. While the
target that failed and anything depending on it cannot
be built, as much as possible will be built before
stopping.
-f, --force Force the specified targets/task to run (invalidating
any existing stamp file).
-c CMD, --cmd=CMD Specify the task to execute. The exact options
available depend on the metadata. Some examples might
be 'compile' or 'populate_sysroot' or 'listtasks' may
give a list of the tasks available.
-C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
Invalidate the stamp for the specified task such as
'compile' and then run the default task for the
specified target(s).
-r PREFILE, --read=PREFILE
Read the specified file before bitbake.conf.
-R POSTFILE, --postread=POSTFILE
Read the specified file after bitbake.conf.
-v, --verbose Enable tracing of shell tasks (with 'set -x'). Also
print bb.note(...) messages to stdout (in addition to
writing them to ${T}/log.do_<task>).
-D, --debug Increase the debug level. You can specify this more
than once. -D sets the debug level to 1, where only
bb.debug(1, ...) messages are printed to stdout; -DD
sets the debug level to 2, where both bb.debug(1, ...)
and bb.debug(2, ...) messages are printed; etc.
Without -D, no debug messages are printed. Note that
-D only affects output to stdout. All debug messages
are written to ${T}/log.do_taskname, regardless of the
debug level.
-q, --quiet Output less log message data to the terminal. You can
specify this more than once.
-n, --dry-run Don't execute, just go through the motions.
-S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
Dump out the signature construction information, with
no task execution. The SIGNATURE_HANDLER parameter is
passed to the handler. Two common values are none and
printdiff but the handler may define more/less. none
means only dump the signature, printdiff means compare
the dumped signature with the cached one.
-p, --parse-only Quit after parsing the BB recipes.
-s, --show-versions Show current and preferred versions of all recipes.
-e, --environment Show the global or per-recipe environment complete
with information about where variables were
set/changed.
-g, --graphviz Save dependency tree information for the specified
targets in the dot syntax.
-I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
Assume these dependencies don't exist and are already
provided (equivalent to ASSUME_PROVIDED). Useful to
make dependency graphs more appealing
-l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
Show debug logging for the specified logging domains
-P, --profile Profile the command and save reports.
-u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp
- default knotty).
--token=XMLRPCTOKEN Specify the connection token to be used when
connecting to a remote server.
--revisions-changed Set the exit code depending on whether upstream
floating revisions have changed or not.
--server-only Run bitbake without a UI, only starting a server
(cooker) process.
-B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind
to.
-T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
Set timeout to unload bitbake server due to
inactivity, set to -1 means no unload, default:
Environment variable BB_SERVER_TIMEOUT.
--no-setscene Do not run any setscene tasks. sstate will be ignored
and everything needed, built.
--setscene-only Only run setscene tasks, don't run any real tasks.
--remote-server=REMOTE_SERVER
Connect to the specified server.
-m, --kill-server Terminate any running bitbake server.
--observe-only Connect to a server as an observing-only client.
--status-only Check the status of the remote bitbake server.
-w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
Writes the event log of the build to a bitbake event
json file. Use '' (empty string) to assign the name
automatically.
--runall=RUNALL Run the specified task for any recipe in the taskgraph
of the specified target (even if it wouldn't otherwise
have run).
--runonly=RUNONLY Run only the specified task within the taskgraph of
the specified targets (and any task dependencies those
tasks may have).

1.5.2. Примеры

1.5.2.1. Выполнение задач для одного задания

Выполнение задачи для одного задания сравнительно просто. BitBake анализирует указанный файл и выполняет задачу. Если задача не указана, BitBake выполняет принятую по умолчанию задачу build. BitBake всегда соблюдает зависимости между задачами.

Например, команда bitbake -b foo_1.0.bb будет выполнять задачу build для foo_1.0.bb, а команда bitbake -b foo.bb -c clean — задачу clean для foo_1.0.bb. Опция -b явно отменяет обработку зависимостей для задания.

1.5.2.2. Выполнение задач для набора заданий

Управление несколькими файлами .bb вызывает ряд сложностей. Ясно, что должен быть способ указать BitBake, какие файлы доступны и какие нужно выполнить. Кроме того, каждое задание должно указать свои зависимости как при сборке, так и при работе. Должен быть способ указать выбора заданий при обеспечении одних функций разными заданиями или при наличии нескольких версий задания.

Команда без опций —buildfile и -b воспринимает лишь PROVIDES и нет возможности предоставить что-либо иное. По умолчанию файл задания обычно указывает в PROVIDES свое имя пакета (packagename), как показано ниже.

     $ bitbake foo

В следующем примере PROVIDES содержит имя пакета и используется опция -c, заставляющая BitBake выполнить задачу do_clean.

     $ bitbake -c clean foo

1.5.2.3. Выполнение списка задач и заданий

Команды BitBake поддерживают указание разных задач для отдельных целей при задании нескольких целей. Например, имеется две цели (или задания) myfirstrecipe и mysecondrecipe и нужно указать BitBake задачу taskA для первого и taskB для второго. Это можно сделать командой вида

     $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB

1.5.2.4. Построение графа зависимостей

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

При создании графа зависимостей BitBake записывает в текущий рабочий каталог 3 файла:

recipe-depends.dot показывает зависимости между заданиями (сжатый вариант task-depends.dot);
task-depends.dot показывает зависимости между задачами, соответствующие внутреннему списку выполнения;
pn-buildlist показывает простой список целей, для которых выполняется сборка.

Для отключения базовых зависимостей служит опция -I и BitBake исключает эти зависимости из графа, что может сделать граф более читаемым. Таким образом можно удалить из графа DEPENDS унаследованных классов, например, base.bbclass. Ниже приведены два примера построения графа и во втором пропускаются базовые зависимости OE.

     $ bitbake -g foo
     $ bitbake -g -I virtual/kernel -I eglibc foo

1.5.2.5. Сборка с несколькими конфигурациями

BitBake может собирать в одной команде множество образов или пакетов, где разным целям нужны разные конфигурации. В таком сценарии каждую цель обозначают multiconfig. Для сборки с множеством конфигураций нужно задать конфигурацию отдельно для каждой цели с использованием файла параллельной конфигурации в каталоге сборки. Файлы конфигураций multiconfig должны размещаться внутри текущего каталога сборки в подкаталоге conf/multiconfig, как показано на рисунке для двух целей.

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

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

Помимо файлов конфигурации для каждой цели, нужно также разрешить BitBake выполнять сборку для множества конфигураций. Это делается путем установки переменной BBMULTICONFIG в файле local.conf. В качестве примера рассмотрим конфигурационные файлы для целей target1 и target2, определенные в каталоге сборки. Приведенная ниже строка в файле local.conf позволит BitBake выполнить сборку для двух multiconfig.

     BBMULTICONFIG = "target1 target2"

Когда конфигурационные файлы для целей созданы и BitBake разрешена сборка для нескольких конфигураций, применяется команда вида

$ bitbake [multiconfig:multiconfigname:]target [[[multiconfig:multiconfigname:]target] ... ]

Для помянутого выше примера с target1 и target2 команда будет иметь форму

$ bitbake multiconfig:target1:target multiconfig:target2:target

1.5.2.6. Включение зависимостей при сборке с множеством конфигураций

Иногда при сборке с множеством конфигураций могут существовать зависимости между целями (multiconfig). Например, при сборке образа для определенной архитектуры может потребоваться корневая файловая система для иной архитектуры. Иными словами, образ для первой конфигурации multiconfig зависит от корневой файловой системы второй multiconfig. Эта зависимость по существу заключается в том, что задача в задании для одной конфигурации multiconfig зависит от выполнения задания для другой конфигурации multiconfig. Для включения зависимостей при сборке с несколькими конфигурациями нужно объявить зависимости в задании, как показано ниже.

task_or_package[mcdepends] = "multiconfig:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"

Для более детальной иллюстрации рассмотрим пример в 2 multiconfig — target1 и target2.

image_task[mcdepends] = "multiconfig:target1:target2:image2:rootfs_task"

Здесь from_multiconfig — это target1, а to_multiconfig — target2. Задача, для которой образ с заданием содержит image_task, зависит от завершения задачи rootfs_task,
используемой для сборки image2, связанного с target2.

После установки зависимости можно собрать target1, используя команду

$ bitbake multiconfig:target1:image1

Эта команда выполняет все задачи, нужные для создания image1 в target1 multiconfig. Зависимость заставляет BitBake выполнить также задачу rootfs_task для сборки target2 multiconfig.

Зависимость задания от корневой файловой системы другой сборки может показаться не очень полезной. Рассмотрим измененный вариант задания image1.

image_task[mcdepends] = "multiconfig:target1:target2:image2:image_task"

В этом случае BitBake нужно создать image2 для сборки target2, от которой зависит сборка target1. Поскольку target1 и target2 включены для сборок с несколькими конфигурациями и имеют разные конфигурационные файлы, BitBake помещает результаты каждой сборки в свой временный сборочный каталог.

Глава 2. Выполнение

Основной целью запуска BitBake является тот или иной вывод (установочный пакет, ядро, SDK или даже полный загружаемый образ Linux с ядром, загрузчиком и корневой файловой системой). Можно запускать bitbake с опциями для выполнения одной задачи, сборки одного задания, извлечения или очистки данных или получения данных о среде.

В этой главе полностью рассматривается процесс работы BitBake от старта до завершения. Для запуска служит команда вида

$ bitbake target

Информация о командах и опциях BitBake приведена в разделе 1.5. Команда bitbake.

Перед выполнением BitBake следует включить параллельную работу на хосте сборки с помощью переменной BB_NUMBER_THREADS в конфигурационном файле проекта local.conf. Для определения значения переменной можно воспользоваться командой grep processor /proc/cpuinfo, которая покажет число процессорных ядер хоста. В некоторых дистрибутивах Linux (например, Debian и Ubuntu) задачу можно решить с помощью команды ncpus.

2.1. Анализ базовых метаданных

Первым делом BitBake выполняет синтаксический анализ данных базовой конфигурации, хранящихся в файле bblayers.conf вашего проекта, который указывает BitBake нужные уровни, файлы layer.conf (1 на каждом уровне) и bitbake.conf. Сами данные включают три различных типа:

задания содержат детали отдельных программных компонент;
данные классов — абстракция базовых данных сборки (например, как собирать ядро Linux)
данные конфигурации — машинозависимые настройки, правила и т. п., собирающие конфигурацию воедино.

Файлы layer.conf служат для создания таких переменных, как BBPATH и BBFILES. Первая служит для поиска файлов конфигурации и классов в каталогах conf и classes, а вторая — для поиска файлов заданий и дополнений (.bb и .bbappend). При отсутствии файла bblayers.conf предполагается, что пользователь установил переменные BBPATH и BBFILES непосредственно в рабочей среде.

Далее с помощью созданной переменной BBPATH отыскивается файл bitbake.conf,
который может включать дополнительные файлы с помощью директив include и require.

Перед анализом конфигурационных файлов Bitbake просматривает ряд переменных, включая:

BB_ENV_WHITELIST;
BB_ENV_EXTRAWHITE;
BB_PRESERVE_ENV;
BB_ORIGENV;
BITBAKE_UI.

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

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

BitBake сначала просматривает текущий рабочий каталог в поиске conf/bblayers.conf,
где
предполагается переменная BBLAYERS с разделенным пробелами списков каталогов уровней. Если BitBake не находит файл bblayers.conf, предполагается установка пользователем переменных BBPATH и BBFILES непосредственно в окружении. Для каждого каталога (уровня) из списка отыскивается и анализируется файл conf/layer.conf с установкой в переменной LAYERDIR имени каталога, содержащего уровень. Идея состоит в автоматической установке BBPATH и других переменных с учетом данного каталога сборки.

Затем BitBake ищет файл conf/bitbake.conf по заданной пользователем переменной BBPATH. Этот файл обычно использует директивы include для добавления других метаданных, относящихся к архитектуре, машине, локальному окружению и т. п.

В файлах .conf можно указывать лишь определения переменных и директивы include. Неrоторые переменные напрямую влияют на поведение BitBake. Такие переменные могут быть установлены непосредственно из среды в зависимости от переменных окружения, упомянутых выше, и установок в файлах конфигурации.

После анализа конфигурационных файлов BitBake использует механизм наследования для некоторых стандартных классов, анализируя класс при наличии указывающей его директивы inherit. Класс base.bbclass включается всегда, как и другие классы, указанные в конфигурации переменной INHERIT. BitBake ищет файлы классов в каталоге classes по пути BBPATH
как
и конфигурационные файлы. Хорошим способом узнать о файлах конфигурации и классах, используемых в среде выполнения является команда bitbake -e > mybb.log. Файлы классов и конфигурации будут указаны в начале файла mybb.log.

Нужно понимать, как BitBake анализирует фигурные скобки. Если в задании используется закрывающая фигурная скобка внутри функции без предшествующих пробелов, анализ BitBake завершается ошибкой. При использовании пары фигурных скобок в функции оболочки закрывающая скобка не должна указываться в начале строки без предшествующих пробелов. Ниже приведен пример, при анализе которого BitBake выдаст ошибку.

fakeroot create_shar() {
     cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
usage()
{
  echo "test"
  ###### The following "}" at the start of the line causes a parsing error ######
}
EOF
}

Приведенный ниже вариант ошибки не вызовет.

fakeroot create_shar() {

cat << «EOF» > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh

usage()

{

echo «test»

#####The following «}» with a leading space at the start of the line avoids the error #####

}

EOF

}

2.2. Нахождение и анализ заданий

В фазе настройки BitBake устанавливает переменную BBFILESи использует ее для создания списка заданий вместе с файлами дополнения(.bbappend) для выполнения. BBFILES содержит разделенный пробелами список файлов, в именах которых можно использовать шаблоны, как показано ниже.

     BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"

BitBake анализирует каждое задание и дополнение из переменной BBFILES и записывает значения переменных в хранилище. Файлы дополнения применяются в порядке их следования в BBFILES.

Для каждого файла создается свежая копия базовой конфигурации, после чего задание анализируется построчно. Для каждого оператора inherit BitBake находит и анализирует файл класса (.bbclass), используя для поиска BBPATH. В заключение BitBake анализирует по порядку все файлы дополнения, найденные в BBFILES. Применяется базовое соглашение — использовать имя задания для определения частей метаданных. Например, в bitbake.conf имя и версия задания могут использоваться для определения переменных PN и PV, как показано ниже.

PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"

В этом примере задание something_1.2.3.bb установит для PN значение something, а для PV — 1.2.3.

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

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

Имеются наборы файлов заданий, позволяющие пользователю держать множество репозиториев файлов .bb для одного пакета. Например, можно их использовать для создания своей копии восходящего репозитория с изменениями, которые в этом репозитории не нужны.

    BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
    BBFILE_COLLECTIONS = "upstream local"
    BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
    BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
    BBFILE_PRIORITY_upstream = "5"
    BBFILE_PRIORITY_local = "10"

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

2.3. Провайдеры

После получения команды и завершения анализа заданий BitBake начинает выяснять, как собрать цель, просматривая список PROVIDES для каждого задания, включающий имена, под которыми задание может быть известно. Список PROVIDES в каждом задании может задаваться неявно через переменную PN или явно через необязательную переменную PROVIDES. При использовании переменной PROVIDESфункциональность задания может быть найдена с другим именем, нежели задано в PN. Например, задание keyboard_1.0.bb может включать строку PROVIDES += «fullkeyboard». Список PROVIDES для этого задания принимает значение keyboard (неявное) и fullkeyboard (явное). В результате функциональность keyboard_1.0.bb может быть найдена по двум именами.

2.4. Предпочтения

Список PROVIDES обеспечивает лишь часть решения для заданий цели. Поскольку у цели может быть множество провайдеров, BitBake нужно расставить приоритеты для выбора. Типичным примером цели с множеством провайдеров является virtual/kernel в списках PROVIDES каждого задания для ядра. Зачастую каждая машина выбирает лучшего поставщика ядра, указывая в своем конфигурационном файле строку вида

     PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"

Используемый по умолчанию PREFERRED_PROVIDER является поставщиком с указанным переменной именем. BitBake перебирает все нужные цели для построения и выполнения зависимостей.

Выбор провайдера осложняется возможностью наличия у данного поставщика множества версий. По умолчанию BitBake выбирает старшую версию, сравнивая номера как принято в Debian. Можно указать предпочтительную версию в переменной PREFERRED_VERSION,а порядок можно менять с помощью переменнойDEFAULT_PREFERENCE.

По умолчанию файлы имеют уровень предпочтения 0. Установка DEFAULT_PREFERENCE = «-1» делает выбор задания маловероятным, если оно не указано явно. Установка DEFAULT_PREFERENCE = «1» делает использование задания вероятным. PREFERRED_VERSION переопределяет установку DEFAULT_PREFERENCE,которая часто применяется для маркировки новых и экспериментальных версий задания, пока оно не будет сочтено стабильным.

При наличии множества «версий» данного задания BitBake по умолчанию выбирает наиболее свежую, если не задано иное. Если в рассматриваемом задании установлено DEFAULT_PREFERENCE ниже, чем в других заданиях (по умолчанию 0), оно не будет выбрано. Это позволяет сопровождающим репозиторий задания указать свои предпочтения для выбираемой по умолчанию версии. Пользователь также может задать предпочтительную версию.

Если первое задание называется a_1.1.bb, переменная PN будет иметь значение a, PV — 1.1. Если имеется задание a_1.2.bb, BitBake по умолчанию выберет его. Однако можно указать в файле .conf, анализируемом BitBake, переменную PREFERRED_VERSION_a = «1.1».

Обычно в задании указывают две версии — стабильную с номером (предпочтительная) и автоматически извлекаемую из репозитория, которая считается «передовой», но может быть выбрана только явно. Например, в базе кодов OE имеется стандартное задание BusyBox с версией — busybox_1.22.1.bb, а также Git-версия busybox_git.bb, для которой указано DEFAULT_PREFERENCE = «-1», чтобы отдать предпочтение стабильной версии.

2.5. Зависимости

Сборка каждой цели в BitBake состоит из множества задач, включая выборку, распаковку, применение правок (patch), настройку и компиляцию. Для обеспечения высокой производительности на многоядерных системах BitBake рассматривает каждую задачу как независимую единицу со своим набором зависимостей, определяемых несколькими переменными (Глава 5. Глоссарий переменных). На базовом уровне достаточно разобраться с использованием переменных DEPENDS и RDEPENDS.Обработка зависимостей вBitBake рассмотрена в разделе 3.10. Зависимости.

2.6. Список задач

На основе созданного списка провайдеров и данных о зависимостях BitBake может точно рассчитать порядок выполнения задач (3.6. Задачи). Сборка начинается с того, что BitBake организует множество потоков, вплоть до значения BB_NUMBER_THREADS. Ветвление продолжается, пока есть задачи для запуска и не превышен предел. Следует отметить, что значение переменной BB_NUMBER_THREADS существенно влияет на производительность.

По завершении каждой задачи записывается временная мета в каталог, заданный переменной STAMP. При следующем запуске BitBake просматривает каталог сборки и не повторяет задачи с действительной временной меткой. Действие метки определяется на уровне файла задания. Например, если штамп задачи configure имеет временную метку, превышающую метку для задачи compile, компиляция будет запущена снова, однако это не будет влиять на других провайдеров, зависящих от этой цели.

Формат штампов частично настраивается и в современных версиях BitBake к штампу добавляется хэш-значение, что позволяет автоматически делать непригодным прежний штамп при изменении конфигурации. Это хэш-значение (подпись) определяется выбранной политикой подписей (2.8. Контрольные суммы (подписи)). Можно также добавить к штампу дополнительные метаданные с помощью флага задачи [stamp-extra-info]. Например, OE применяет этот флаг для задания зависимости некоторых задач от машины. Некоторые задачи помечаются как nostamp и штампы для них не создаются, что приводит к перезапуску такой задачи всякий раз.

2.7. Выполнение задач

Задачи могут выполняться в оболочке (shell) или Python. Для shell-задач BitBake записывает сценарий в файл ${T}/run.do_taskname.pid и выполняет его. Созданный сценарий содержит все экспортируемые переменные и функции оболочки с преобразованными переменными. Вывод сценария записывается в файл ${T}/log.do_taskname.pid. Просмотр преобразованных shell-функций в файле run и вывода в файле log полезен при отладке.

Задачи Python выполняются внутри BitBake с выводом информации на терминал управления. В новых версиях BitBake будет записывать функции и вывод в файлы, как это делается для shell-задач.

Порядок выполнения задач контролируется планировщиком, который можно настроить для конкретных ситуаций через переменные BB_SCHEDULER и BB_SCHEDULERS.Функции могут выполняться до и после основной задачи. Это управляется с помощью флагов[prefuncs] и [postfuncs] в списке выполняемых задач.

2.8. Контрольные суммы (подписи)

Контрольная сумма является уникальной подписью ввода в задачу и может служить для решения вопроса о перезапуске задачи. Поскольку изменение ввода ведет к перезапуску задач, BitBake нужно детектировать изменение ввода. Для shell-задач это достаточно просто, поскольку BitBake создает сценарии run для каждой задачи и можно рассчитать контрольную сумму, которая покажет изменение данных задачи. Однако в контрольную сумму включается не все. Во-первых, имеется фактический путь сборки задачи — рабочий каталог и его изменение не должно влиять на вывод целевых пакетов. Упрощенный вариант исключения рабочего каталога из контрольной суммы заключается в установке фиксированного значения. BitBake идет дальше и применяет переменную BB_HASHBASE_WHITELIST для задания списка переменных, которые не следует учитывать в контрольных суммах.

Другая проблема связана с наличием в сценариях run функций, которые могут не вызываться. Решение для инкрементальной сборки содержит код, учитывающий зависимости между shell-функциями, который служит для урезания сценариев run до минимального набора функций, что существенно смягчает эту проблему и делает сценарии более читаемыми.

Такой же подход применяется к задачам Python. Процесс должен выяснить переменные, к которым обращается функция Python, и вызываемые ею функции. Решение для инкрементальной сборки содержит код, который сначала определяет зависимости переменных и функций, а затем создает контрольную сумму для входных данных задачи. Как и для рабочих каталогов, имеются случаи, где следует игнорировать зависимости. В таких ситуациях можно указать это процессу сборки в виде PACKAGE_ARCHS[vardepsexclude] = «MACHINE», где указано, что переменная PACKAGE_ARCHS не зависит от значения MACHINE, даже если она ссылается на нее. Существуют и случаи, когда нужно добавить зависимости, которые BitBake не может найти. Это можно сделать в форме PACKAGE_ARCHS[vardeps] = «MACHINE», где переменная MACHINE явно указана как зависимость для PACKAGE_ARCHS.

Возможен случай с Python, где BitBake не может определить зависимости. При работе в режиме отладки (-DDD), BitBake выдает сообщения при обнаружении невозможности выяснить зависимости.

На уровне кода есть много способов воздействия на хэш-значения. В файле конфигурации BitBake можно задать дополнительные данные для создания basehash. Приведенное ниже выражение из OE фактически исключает зависимости от глобальных переменных (т. е. они не включаются в контрольную сумму).

     BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
         SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
         USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
         PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
         CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"

В примере не указан рабочий каталог, являющийся частью TMPDIR.

Правила включения хэш-значений с учетом цепочек зависимостей являются более сложными и обычно реализуются функциями Python. Код в файле meta/lib/oe/sstatesig.py содержит два примера т показывает, как можно включить свои правила в систему. Этот файл определяет два базовых генератора подписей, используемых в OpenEmbedded-Core, — OEBasic и OEBasicHash. По умолчанию в BitBake включен фиктивный обработчик подписей noop. Это означает, что поведение не отличается от предыдущих версий. OE-Core использует по умолчанию обработчик OEBasicHash (файл bitbake.conf)

     BB_SIGNATURE_HANDLER ?= "OEBasicHash"

BB_BASEHASH_task-taskname — базовые хэш-значения для каждой задачи в задании;
BB_BASEHASH_filename:taskname — базовые хэш-значения для каждой зависимой задачи;
BBHASHDEPS_filename:taskname — зависимости для каждой задачи;
BB_TASKHASH — хэш текущей работающей задачи.

Отметим, что опция -S позволяет отлаживать подписи в BitBake, поддерживая различные режимы с использованием отладочных функций BitBake или указанного в метаданных/подписи обработчика. Простейшим параметром является none, обеспечивающий вывод информации о подписях в каталог STAMPS_DIR указанной цели. Указание параметра printdiff заставляет BitBake пытаться найти максимальное соответствие (например, в кэше sstate), а затем запустить bitbake-diffsigs для совпадений с целью определения штампа и места, где дерево штампов расходится. В новых версиях BitBake могут появиться другие обработчики подписей, запускаемые новыми параметрами опции -S. Информация о контрольных суммах метаданных приведена в параграфе 3.12. Контрольные суммы задач и Setscene.

2.9. Setscene

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

Когда у BitBake запрошена сборка данной цели, программа сначала проверяет доступность кэшированных данных для собираемых или промежуточных целей. При наличии такой информации BitBake использует ее вместо запуска задач. Сначала BitBake вызывает функцию, определенную переменной BB_HASHCHECK_FUNCTION, со списком задач и соответствующих хэш-значений для планируемой сборки. Эта функция обеспечивает быстрый возврат списка задач, для которых могут быть получены собранные результаты. Затем для каждой возвращенной задачи BitBake выполняет setscene-версию, включающую возможный результат. Setscene-версии задач имеют суффикс _setscene. Эти задачи выполняются и предоставляют нужные элементы (возможно, возвращая вместо этого отказ).

Как было отмечено выше, элемент может охватывать несколько задач. Например, нет смысла получать компилятор при наличии скомпилированной версии. Для обработки таких ситуаций BitBake вызывает функцию BB_SETSCENE_DEPVALID для каждой успешной задачи setscene, чтобы решить вопрос о получении зависимостей этой задачи.

После выполнения всех задач setscene BitBake вызывает функцию, указанную в BB_SETSCENE_VERIFY_FUNCTION2,со списком задач, которыеBitBake считает «охваченными». Метаданные могут гарантировать корректность списка и информировать BitBake о необходимости перезапуска определенной задачи, независимо от результата setscene.

Метаданные setscene описаны в параграфе 3.12. Контрольные суммы задач и Setscene.

Глава 3. Синтаксис и операторы

Файлы Bitbake используют свой синтаксис, который похож на синтаксис других языков, но имеет особенности.

3.1. Базовый синтаксис

3.1.1. Установка переменных

Для незамедлительной установки в переменной VARIABLE значения value используется выражение VARIABLE = «value». Такое назначение называется «жестким» (hard). Если назначаемое значение включает пробел, он сохраняется.

     VARIABLE = " value"
     VARIABLE = "value "

Установка «» делает переменную пустой, а » » помещает в нее пробел (это разные вещи).

     VARIABLE = ""
     VARIABLE = " "

Вместо двойных кавычек можно применять одинарные, что позволяет включать в значение двойные кавычки.

     VARIABLE = 'I have a " in my value'

В отличие от оболочек Bourne одинарные кавычки эквивалентны двойным и не препятствуют преобразованию переменных.

3.1.2. Изменение имеющихся переменных

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

отредактировать задание, включающее переменную;
изменить принятое по умолчанию значение переменной в файле класса .bbclass;
изменить переменную в файле дополнения .bbappend для переопределения ее значения;
изменить переменную в файле конфигурации для переопределения ее значения.

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

Для проверки конфигурационных изменений служит команда bitbake -e, которая выводит значения переменных после анализа файлов конфигурации (local.conf, bblayers.conf, bitbake.conf и т. п.). Экспортируемые в среду переменные имеют префикс export в выводе команды.
Для проверки изменений в задании служит команда bitbake recipe -e | grep VARIABLE=», которая позволяет проверить реальное значение переменной VARIABLE.

3.1.3. Объединение строк

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

     FOO = "bar \
            baz \
            qaz"

При объединении символ \ и символы новой строки удаляются и строка FOOполучит значение "barbaz qaz". Ниже приведены два варианта присвоения значения barbaz переменной FOO.

     FOO = "barbaz"
     FOO = "bar\
     baz"

BitBake не интерпретирует последовательности типа \n в значениях переменных. Для специальной трактовки их следует передавать таким утилитам как printf или echo -n.

3.1.4. Преобразование переменных

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

     A = "aval"
     B = "pre${A}post"

В отличие от Bourne фигурные скобки обязательны и преобразование выполняется лишь для ${FOO},но не для $FOO.

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

     A = "${B} baz"
     B = "${C} bar"
     C = "foo"

В этот момент ${A} имеет значение «foo bar baz».

     C = "qux"

В этот момент ${A} имеет значение «qux bar baz».

     B = "norf"

В этот момент ${A} имеет значение «norf baz».

Другое поведение обеспечивается оператором незамедлительного преобразования :=.

Если синтаксис преобразования использован для несуществующей переменной, назначение сохраняется буквально. Например, при указании BAR = «${FOO}» строка BAR получит значение ${FOO}, если переменной FOO не существует.

3.1.5. Установка с сохранением принятого по умолчанию значения (?=)

Можно использовать оператор ?= для «более мягкого» назначения переменной. Этот оператор позволяет определить переменную, если на момент анализа она еще не была определена, но сохраняет значение, если переменная уже задана. Например, при анализе выражения A ?= «aval» будет сохранено имеющееся значение переменной или задано значение aval, если переменная еще не была назначена. Это присвоение выполняется сразу же, поэтому при наличии нескольких операторов ?= для одной переменной работать будет лишь первое.

3.1.6. Отложенная установка с сохранением заданной по умолчанию (??=)

Можно использовать более «слабый» вариант описанного в предыдущем параграфе оператора — ??=, который похож на ?=, но присвоение выполняется не сразу, а в конце процесса анализа. Поэтому при наличии нескольких операторов ??= действовать будет последний. Любые назначения = или ?= будут переопределять ??=. Например,

     A ??= "somevalue"
     A ??= "someothervalue"

Если переменная A была установлена до анализа этих операторов, она сохранит значение, в противном случае получит значение someothervalue.

3.1.7. Незамедлительное преобразование переменной (:=)

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

     T = "123"
     A := "${B} ${A} test ${T}"
     T = "456"
     B = "${T} bval"
     C = "cval"
     C := "${C}append"

В этом примере A получит значение «test 123» поскольку ${B} и ${A} в момент анализа не определены, а переменная C — «cvalappend», поскольку ${C} сразу же преобразуется в «cval».

3.1.8. Добавление в конец (+=) и в начало (=+) с пробелом

Добавление значения в конец или в начало переменной обеспечивается операторами += и =+, которые помещают пробел между имеющимся и добавленным значением. Эти назначения выполняются сразу же при анализе. Например,

     B = "bval"
     B += "additionaldata"
     C = "cval"
     C =+ "test"

Переменная B получит значение «bval additionaldata» а C — «test cval».

3.1.9. Добавление в (.=) и в начало (=.) без пробела

Для добавления в конец или начало переменной значения без пробела служат операторы .= и =., которые выполняются сразу же при анализе.

     B = "bval"
     B .= "additionaldata"
     C = "cval"
     C =. "test"

Переменная B получит значение «bvaladditionaldata», а C — «testcval».

3.1.10. Добавление в начало или в конец с переопределением

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

     B = "bval"
     B_append = " additional data"
     C = "cval"
     C_prepend = "additional data "
     D = "dval"
     D_append = "additional data"

Переменная B в результате становится «bval additional data», C — «additional data cval», а D — «dvaladditional data».

При использовании этого синтаксиса следует самостоятельно контролировать добавление пробелов. Можно также применять операторы append и prepend к функциям оболочки и функциям Python в стиле BitBake. Примеры приведены в параграфах 3.5.1. Функции оболочки и 3.5.2. Функции Python в стиле BitBake.

3.1.11. Удаление

Можно удалять значения из списков с помощью синтаксиса переопределения. Указание удаляемого значения ведет к исключению из переменной всех его вхождений. При использовании этого синтаксиса BitBake предполагает указание одной или нескольких строк, Например,

     FOO = "123 456 789 123456 123 456 123 456"
     FOO_remove = "123"
     FOO_remove = "456"
     FOO2 = "abc def ghi abcdef abc def abc def"
     FOO2_remove = "abc def"

Переменная FOO в результате станет » 789 123456 «, FOO2 — » ghi abcdef «. Подобно _append и _prepend, оператор _remove применяется по завершении синтаксического анализа.

3.1.12. Преимущества стиля переопределения

Преимущество операторов стиля переопределения _append, _prepend и _remove по сравнению с += и =+ заключается в том, что они обеспечивают гарантированные операции. Рассмотрим в качестве примера класс foo.bbclass,который должен добавить значениеval к переменной FOO, и задание, использующее foo.bbclass,как показано ниже.

     inherit foo
     FOO = "initial"

Если foo.bbclass использует оператор +=, как показано ниже, значением FOO будет «initial», что не устраивает.

     FOO += "val"

Если же foo.bbclass применяет оператор _append, переменная FOO получит нужно значение «initial val».

     FOO_append = " val"

Никогда не следует применять += вместе с _append. Приведенные ниже операторы добавляют «barbaz» в конец FOO.

     FOO_append = "bar"
     FOO_append = "baz"

Если во втором выражении применить оператор +=, это добавить в окончательный результат пробел перед «baz».

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

3.1.13. Синтаксис флагов переменных

Флаги переменных в BitBake служат реализацией свойств или атрибутов переменных, позволяя связывать с ними дополнительную информацию. Описание флагов приведено в разделе 3.7. Флаги переменных.

Флаги можно определять и добавлять в начало или в конец имеющихся. Все описанные выше стандартные операции, кроме синтаксиса стиля переопределения, применимы к флагам (например, _prepend, _append и _remove). Например,

     FOO[a] = "abc"
     FOO[b] = "123"
     FOO[a] += "456"

Переменная FOO имеет флаги [a] и [b],для которых сразу же устанавливаются значенияabc и 123. Затем флаг [a] становится «abc 456». Нет нужды в создании предопределенных флагов переменных, поскольку начать их использование можно в любой момент. Одним из наиболее распространенных применений флагов является краткое описание переменных BitBake в форме CACHE[doc] = «The directory holding the cache of the metadata.».

3.1.14. Преобразование переменных Python

Можно использовать встроенное в Python преобразование переменных для установки значений. Например,

     DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"

Для переменной DATE будет установлено текущее время.

Возможно наиболее частым применением этой функции является извлечение значений переменных из внутреннего словаря BitBake (d). Приведенные ниже строки извлекают имя и версию пакета.

     PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
     PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"

Inline-выражения Python работают как преобразования переменных с операторами = и :=. Например, при назначении FOO = «${@foo()}» функция foo() будет вызываться при каждом преобразовании FOO.При назначении FOO := "${@foo()}" функцияfoo() будет вызываться лишь однократно при анализе назначения. Другой способ установки переменных в коде Python при синтаксическом анализе описан в параграфе 3.5.5. Анонимные функции Python.

3.1.15. Отмена переменных

Можно полностью удалить переменную или флаг из внутреннего словаря данных BitBake с помощью оператора unset.

        unset DATE
        unset do_fetch[noexec]

3.1.16. Указание путей

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

     BBLAYERS ?= " \
       /home/scott-lenovo/LayerA \
       "

3.2. Экспорт переменных в среду

Можно экспортировать переменные в среду выполняемых задач с помощью оператора export. Например, задача do_foo будет при работе печатать «value from the environment», если задать

     export ENV_VARIABLE
     ENV_VARIABLE = "value from the environment"

     do_foo() {
         bbplain "$ENV_VARIABLE"
     }

BitBake не преобразует в этом случае переменную $ENV_VARIABLE по причине отсутствия фигурных скобок и переменная преобразуется оболочкой. Размещение строки export ENV_VARIABLE относительно присвоения значения переменной не играет роли. Можно объединить назначение и экспорт в форме export ENV_VARIABLE = «variable-value«.

В выводе команды bitbake -eэкспортируемые в среду переменные помечаются префиксомexport.

Обычно экспортируемые переменные включают CC и CFLAGS, которые принимают многие системы сборки.

3.3. Синтаксис условий

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

3.3.1. Условные метаданные

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

Выбор переменной. OVERRIDES содержит список разделенных двоеточиями элементов, для которых нужно выполнить условия. Например, если есть условная переменная для arm и arm входит в OVERRIDES, будет использована связанная с arm версия переменной вместо безусловной. Например,
```
     OVERRIDES = "architecture:os:machine"
     TEST = "default"
     TEST_os = "osspecific"
     TEST_nooverride = "othercondvalue"    
```
OVERRIDES содержит 3 переопределения — architecture, os и machine. Переменная TEST по умолчанию имеет значение default. Можно выбрать связанную с os переменную TEST,добавив в конец переопределениеos (TEST_os).

Для лучшего понимания рассмотрим практический пример, предполагающий файл задания для ядра Linux в OE на основе метаданных. Приведенные ниже строки из файла задания сначала устанавливают в переменной ветви ядра KBRANCH принятое по умолчанию значение, затем по условию переопределяют его в соответствии с архитектурой.
```
     KBRANCH = "standard/base"
     KBRANCH_qemuarm  = "standard/arm-versatile-926ejs"
     KBRANCH_qemumips = "standard/mti-malta32"
     KBRANCH_qemuppc  = "standard/qemuppc"
     KBRANCH_qemux86  = "standard/common-pc/base"
     KBRANCH_qemux86-64  = "standard/common-pc-64/base"
     KBRANCH_qemumips64 = "standard/mti-malta64"   
```
Добавление в начало или в конец. BitBake также поддерживает операции добавления в конец и в начало переменной в зависимости от наличия элемента в OVERRIDES. Например,
```
     DEPENDS = "glibc ncurses"
     OVERRIDES = "machine:local"
     DEPENDS_append_machine = " libmad"     
```
DEPENDS в результате принимает значение «glibc ncurses libmad». В примере с заданием для ядра можно использовать условное добавление в конце переменной в зависимости от архитектуры, как показано ниже.
```
     KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
     KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
     KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"           
```
Установка для одной задачи. BitBake поддерживает установку переменной лишь для выполнения 1 задачи.
```
     FOO_task-configure = "val 1"
     FOO_task-compile = "val 2"
```
Здесь переменная FOO имеет значение «val 1» при выполнении задачи do_configure и «val 2» — в do_compile.

Это реализуется путем добавления задачи (например, task-compile:) в начало OVERRIDES для локального хранилища задачи do_compile. Можно также использовать этот синтаксис с другими комбинациями (например, _prepend), как показано ниже.
```
     EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} "
```

3.3.2. Преобразование ключей

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

     A${B} = "X"
     B = "2"
     A2 = "Y"

В этом случае по завершении анализа но перед обработкой перещпределений BitBake преобразует ${B} в 2. Это преобразование меняет значение A2, которое было Y, на X.

3.3.3. Примеры

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

Часто возникает путаница с определением порядка применения переопределений и операторов append. Напомним, что операции _append и _prepend не меняют значения сразу, как это делают операторы =+, =., += и .=.

     OVERRIDES = "foo"
     A = "Z"
     A_foo_append = "X"

В примере выше A безусловно получает значение Z, а X безусловно и незамедлительно добавляется в конец переменной A_foo. Поскольку переопределения еще не было, к A_foo добавляется значение X, а A становится Z. Однако переопределение меняет картину. Поскольку переменная foo указана в OVERRIDES, условная переменная A заменяется версией foo, которая равна X. В результате A_foo заменяет A.

     OVERRIDES = "foo"
     A = "Z"
     A_append_foo = "X"

Здесь перед переопределением в переменной A устанавливается значение Z и A_append_foo становится X. После переопределения foo в конце A добавляется X и A становится ZX. Отметим, что пробел не добавляется.

В следующем примере используется обратный порядок добавления и переопределения.

     OVERRIDES = "foo"
     A = "Y"
     A_foo_append = "Z"
     A_foo_append = "X"

Здесь до переопределения A получает значение Y, затем в A_foo устанавливается значение Z, после чего в конце добавляется X и получается ZX. Затем переопределение foo приводит к тому, что условная переменная A получает значение ZX (A заменяется на A_foo).

     A = "1"
     A_append = "2"
     A_append = "3"
     A += "4"
     A .= "5"

В этом примере тип операторов append влияет на порядок назначений, поскольку BitBake проходит код несколько раз. Изначально в A устанавливается значение «1 45», поскольку три оператора используют незамедлительное назначение. Затем BitBake применяет операторы _append и A становится «1 4523».

3.4. Общая функциональность

BitBake обеспечивает возможность совместного использования метаданных через включаемые файлы (.inc) и классы (.bbclass). Например, можно определить задачу, которая будет применяться в нескольких заданиях. Для этого создается файл класса .bbclass с общей функциональностью и используется директива inherit в заданиях, которым нужна такая задача.

Ниже описаны механизмы BitBake для совместного использования функций — include, inherit, INHERIT и require.

3.4.1. Поиск включаемых файлов и классов

BitBake использует переменную BBPATH для поиска включаемых файлов и классов, просматривая также текущий каталог для директив include и require. Переменная BBPATH похожа на переменную среды PATH. Для того, чтобы включаемые файлы и классы были найдены BitBake, их нужно разместить в каталоге classes, указанном в BBPATH.

3.4.2. Директива inherit

При создании файла задания или класса можно использовать директиву inherit для наследования функциональности класса (.bbclass). BitBake разрешает применять эти директивы только в файлах заданий и классов (.bb и .bbclass).

Директива inherit является элементарным способом указания требуемой заданию функциональности, содержащейся в классе. Например, можно абстрагировать задачи сборки пакета с использованием Autoconf и Automake, поместив их в файл класса, а затем наследовать этот класс в файлах заданий. Например, задания могут использовать директиву inherit autotools для наследования файла autotools.bbclass. В таком случае BitBake будет искать файл classes/autotools.bbclass в BBPATH.

Можно переопределить любые значения и функции наследуемого класса внутри задания после оператора inherit.

Если нужно унаследовать несколько классов, они указываются в директиве inherit через пробелы. Например inherit buildhistory rm_work задает наследование классов buildhistory и rm_work. Преимуществом inherit перед директивами include и require является возможность условного наследования в форме inherit ${VARNAME}. Переменная VARNAME в таких случаях должна быть назначена до оператора inherit. Один из вариантов условного наследования имеет вид

     VARIABLE = ""
     VARIABLE_someoverride = "myclass"

Другим вариантом является использование анонимной функции Python. Например,

     python () {
         if condition == value:
             d.setVar('VARIABLE', 'myclass')
         else:
             d.setVar('VARIABLE', '')
     }

Можно также применять in-line-выражения Python в форме

     inherit ${@'classname' if condition else ''}
     inherit ${@functionname(params)}

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

3.4.3. Директива `include`

Директива include заставляет BitBake анализировать заданный файл и помещать его содержимое в указанное место. Это похоже на одноименную директиву Make, но путь указывается относительный и BitBake включает первый файл, найденный по переменной BBPATH. Директива include обеспечивает более общий по сравнению с inherit способ включения, поскольку наследование ограничено файлами классов (.bbclass). Директива include применима к любому виду общей или инкапсулированной функциональности или конфигурации, которая не подходит для классов (.bbclass).

Например, можно включить в задание те или иные элементы самопроверки в форме include test_defs.inc.

Если включается директивой include файл не найден, ошибки не возникает. Если же нужно обязательно включить файл, следует применять директиву require.

3.4.4. Директива `require`

Директива require похожа на include, но BitBake возвращает ошибку, если файл не найден. Директива require, как и include, является более общим способом включения функциональности нежели inherit, которая работает только для классов (.bbclass). Директива применима для любой общей или инкапсулированной функциональности и конфигурации, которая не подходит для .bbclass. Подобно обработке include, при указании относительного пути в директиве require BitBake использует первый файл, найденный в BBPATH.

Предположим, что имеется 2 задания (например, foo_1.2.2.bb и foo_2.0.0.bb), где каждая версия включает некие общие функции. Можно создать включаемый файл foo.inc с общими определениями для сборки foo. Файл foo.inc должен размещаться в одном каталоге с файлами заданий. После это можно указать в заданиях require foo.inc.

3.4.5. Конфигурационная директива `INHERIT`

При создании конфигурационных файлов (.conf) можно применять директиву INHERIT для наследования классов. Например, можно добавить в конфигурацию наследованием файла abc.bbclass в форме INHERIT += «abc». Эта директива включает наследование указанного класса в точек анализа директивы. Файл .bbclass должен размещаться в каталоге classes одного из каталогов BBPATH. Поскольку файлы .conf анализируются первыми при работе BitBake, использование директивы INHERIT обеспечивает глобальное (для всех заданий) наследование класса. Если нужно наследовать несколько классов, они указываются через пробелы в форме INHERIT += «autotools pkgconfig».

3.5. Функции

Как в большинстве языков, функции являются основными блоками задач. В BitBake имеется несколько типов функций.

Функции оболочки, написанные на языке сценарией, выполняются как функции и/или задачи.
Функции Python в стиле BitBake на языке Python, выполняемые BitBake или другими функциями Python с помощью bb.build.exec_func().
Функции Python, написанные на языке Python и выполняемые Python.
Анонимные функции Python, функции Python, автоматически выполняемые в процессе анализа.

В файлах классов (.bbclass) и заданий (.bb или .inc) можно определять любые функции.

3.5.1. Функции оболочки

Функции оболочки или shell-функции используют язык сценариев оболочки и выполняются как задачи и/или функции. Их могут также вызывать другие shell-функции.

     some_function () {
         echo "Hello World"
     }

При создании таких функций в классе или задании нужно следовать правилам для программ оболочки. Сценарии выполняются оболочкой /bin/sh, в качестве которой не обязательно служит shell (может быть, например, dash), поэтому не следует применять специфичные для Bash сценарии.

В этих функциях можно применять переопределения и операторы с переопределением. Обычно это применяется в файлах .bbappend для изменения функций основного задания или унаследованных функций класса. Например,

     do_foo() {
         bbplain first
         fn
     }

     fn_prepend() {
         bbplain second
     }

     fn() {
         bbplain third
     }

     do_foo_append() {
         bbplain fourth
     }

Результатом запуска do_foo будет вывод строк

     recipename do_foo: first
     recipename do_foo: second
     recipename do_foo: third
     recipename do_foo: fourth

Переопределения и операторы с переопределением могут применяться не только в задачах, но и в любых shell-функциях. Для просмотра созданных функций после переопределений служит команда bitbake -e recipename.

3.5.2. Функции Python в стиле BitBake

Эти функции на языке Python выполняются BitBake или другими функциями Python с помощью bb.build.exec_func().

     python some_python_function () {
         d.setVar("TEXT", "Hello World")
         print d.getVar("TEXT")
     }

Поскольку модули Python bb и os уже импортированы, импортировать их не нужно. В функциях этого типа хранилище данных (d) является глобальной переменной и доступно всегда.

Выражения с переменными (например, ${X}) не преобразуются в функциях Python, чтобы позволить свободно устанавливать значения переменных в преобразуемые выражения без преждевременного преобразования. Если нужно преобразовать переменную внутри функции Python, следует применять d.getVar("X")илиd.expand().

Как и в shell-функциях можно применять переопределения и операторы с переопределением.

     python do_foo_prepend() {
         bb.plain("first")
     }
     python do_foo() {
         bb.plain("second")
     }

     python do_foo_append() {
         bb.plain("third")
     }

Результатом запуска do_foo будет вывод строк

     recipename do_foo: first
     recipename do_foo: second
     recipename do_foo: third

Для просмотра созданных функций после переопределений служит команда bitbake
-e recipename.

3.5.3. Функции Python

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

     def get_depends(d):
         if d.getVar('SOMECONDITION'):
             return "dependencywithcond"
         else:
             return "dependency"
     SOMECONDITION = "1"
     DEPENDS = "${@get_depends(d)}"

Это будет приводить к включению в DEPENDS значения dependencywithcond.

Функции Python могут принимать параметры, хранилище данных BitBake автоматически не предоставляется и должно передаваться в параметре функции, модули bb и os доступны автоматически и не нужно импортировать их.

3.5.4. Функции в стиле Bitbake и обычные функции Python

Ниже перечислены основные различия функций Python в стиле BitBake и обычных функций, определяемых с def.

Задачами могут быть только функции в стиле BitBake.
Переопределения и операторы с переопределением доступны только в функциях со стилем BitBake.
Только обычные функции Python могут принимать параметры и возвращать значения.
Флаги переменных (такие как [dirs], [cleandirs], [lockfiles]) могут применяться только в функциях стиля BitBake.
Функции в стиле BitBake создают отдельный сценарий ${T}/run.function-name.pid для своего запуска и журнальный файл ${T}/log.function-name.pid при выполнении как задачи. Обычные функции Python выполняются как встроенные (inline) и не создают файлов в ${T}.
Обычные функции Python вызываются с использованием стандартного синтаксиса Python, а функции в стиле BitBake обычно являются задачами и вызываются напрямую из BitBake, но могут вызываться из кода Python с помощью функции bb.build.exec_func(). Например, bb.build.exec_func(«my_bitbake_style_function», d).

Функцию bb.build.exec_func() можно применять также для запуска shell-функций из Python. Если нужно запустить такую функцию в задаче до функции Python можно применить вспомогательную родительскую (parent) функцию Python, которая использует bb.build.exec_func() а затем выполнит код Python.

Для обнаружения ошибок при вызове bb.build.exec_func() можно перехватывать bb.build.FuncFailed. Функциям в метаданных (задания и классы) не следует самим активировать bb.build.FuncFailed. Вместо этого можно просматривать bb.build.FuncFailed как индикатор ошибки при вызове функции путем активизации исключения. Например, активизация bb.fatal() будет захватывать bb.build.exec_func() и вызывать в ответ bb.build.FuncFailed.

Простота обычных функций Python делает их предпочтительней функций в стиле BitBake, если не нужны специфические возможности функций в стиле BitBake. Обычные функции Python появились в метаданных позднее функций в стиле BitBake и старый код более часто применяет bb.build.exec_func().

3.5.5. Анонимные функции Python

Иногда полезно устанавливать переменные и выполнять другие операции в процессе разбора. Для этого можно определять специальные функции Python, названные анонимными, которые выполняются в конце разбора. Например, приведенные ниже функция устанавливает переменную по условию.

     python () {
         if d.getVar('SOMEVAR') == 'value':
             d.setVar('ANOTHERVAR', 'value2')
     }

Другим способом является использованием для анонимных функций имени __anonymous.

Анонимные функции Python всегда применяются в конце анализа независимо от места их определения. При наличии множества анонимных функций в задании они выполняются в порядке определения.

     python () {
         d.setVar('FOO', 'foo 2')
     }

     FOO = "foo 1"
     python () {
         d.appendVar('BAR', ' bar 2')
     }

     BAR = "bar 1"

Приведенный пример концептуально эквивалентен приведенным ниже назначениям.

     FOO = "foo 1"
     BAR = "bar 1"
     FOO = "foo 2"
     BAR += "bar 2"

FOO будут иметь значение «foo 2», а BAR — «bar 1 bar 2». Как и во втором варианте, значения, установленные для переменных в анонимных функциях, доступны для задач, которые всегда зпускаются после анализа.

Переопределения и операторы с переопределением, такие как _append, применяются до выполнения анонимных функций. В приведенном ниже примере FOO получит в результате значение «foo from anonymous».

     FOO = "foo"
     FOO_append = " from outside"

     python () {
         d.setVar("FOO", "foo from anonymous")
     }

Методы, которые можно применять с анонимными функциями, описаны в разделе 3.11. Функции, которые можно вызывать из Python. Другой метод выполнения кода Python в процессе разбора описан в параграфе 3.1.14. Преобразование переменных Python.

3.5.6. Гибкое наследование для функций класса

С помощью методов копирования и использсдщ

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

Для решения такой задачи нужно выполнить приведенные ниже условия.

Класс должен определять функцию в форме classname_functionname. Например,
для класса bar.bbclass и функции do_foo определение будет иметь вид bar_do_foo.
Класс должен включать оператор EXPORT_FUNCTIONS в форме EXPORT_FUNCTIONS functionname. Для предыдущего примера это будет иметь
вид EXPORT_FUNCTIONS do_foo.
Нужно соответствующим образом вызвать функцию из задания. Для приведенного примера заданию следует вызвать bar_do_foo. Предположим, что do_foo является shell-функцией и переменная EXPORT_FUNCTIONS указана как было описано выше. Функция в задании может вызвать функцию класса по условию, задав
```
     do_foo() {
             if [ somecondition ] ; then
                     bar_do_foo
             else
                     # Do something else
             fi
     }
```
Для вызова измененной в задании функции применяется do_foo.

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

3.6. Задачи

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

3.6.1. Представление функции задаче

Задачи являются функциями оболочки или функциями Python в стиле BitBake, которые представлены задаче с помощью команды addtask. Эта команда может также описывать зависимости от других задач. Ниже приведен пример определения задачи с указанием зависимостей.

     python do_printdate () {
         import time
         print time.strftime('%Y%m%d', time.gmtime())
     }
     addtask printdate after do_fetch before do_build

Первым аргументом addtask является имя функции, представляемой задаче. Если имя не начинается с do_, этот префикс добавляется неявно в соответствии с принятым соглашением.

В примере задача do_printdate становится зависимjстью do_build, которая выполняется по умолчанию (т. е. будет выполняться командой bitbake, если явно не указана иная задача). Кроме того, do_printdate становится зависимостью do_fetch. Запуск задачи do_build будет приводить к выполнению сначала do_printdate.

Если попытаться выполнить приведенный выше пример, можно будет увидеть, что задача do_printdate запускается только при первой сборке задания по команде bitbake. Это связано с тем, что после этого BitBake считает задачу «не устаревшей» (up-to-date). Если нужно повторять задачу каждый раз при экспериментальных сборках, можно «состарить» ее с помощью флага переменной [nostamp] в форме do_printdate[nostamp] = «1». Можно также явно запускать задачу с опцией -f в форме bitbake recipe -c printdate -f. В этом случае префикс do_ не требуется.

Может возникнуть вопрос о практичности применения addtask без указания зависимости как addtask printdate. В этом случае (если зависимости не были заданы иначе) единственным способом запуска задачи будет bitbake recipe -c printdate. Можно использовать задачу do_listtasks для перечисления определенных в задании задач в форме bitbake recipe -c listtasks. Зависимости между задачами рассмотрены в разделе 3.10. Зависимости, а флаги переменных — в разделе 3.7. Флаги переменных.

3.6.2. Удаление задачи

Задачи можно не только добавлять, но и удалять командой deltask, например, deltask printdate. При удалении с помощью deltask задачи, имеющей зависимости, эти зависимости не включаются заново. Предположим, что имеются 3 задачи do_a, do_b, do_c и do_c зависит от do_b, а та — от do_a. Еcли в этом случае удалить do_b, неявная зависимость между do_c и do_a (через do_b) будет утеряна и зависимости do_c не обновятся для включения do_a. В результате do_c может быть запущена раньше do_a. Если нужно сохранить зависимости, следует применять флаг переменной [noexec] для отключения задачи без ее удаления, в форме do_b[noexec] = «1».

3.6.3. Передача информации в среду сборки задачи

При запуске задачи BitBake строго контролирует среду сборки, чтобы нежелательное «загрязнение» сборочной машины не мешало процессу сборки. По умолчанию BitBake очищает среду для включения лишь тех переменных которые экспортируются или указаны в «белом списке» для обеспечения согласованности и воспроизводимости сборки. Можно отключить такую «очистку» с помощью переменной BB_PRESERVE_ENV.

Для передачи чего-либо в выполняемую задачу нужно выполнить две операции, описанных ниже.

Указать BitBake загрузку нужных переменных из среды в хранилище данных с помощью переменных BB_ENV_WHITELIST и BB_ENV_EXTRAWHITE. Например, для запрета доступа системы сборки в каталог $HOME/.ccache можно включить в «белый список» переменную среды CCACHE_DIR для ее добавления в хранилище данных BitBack.
```
     export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
```
Указать BitBake экспорт включенного в хранилище данных в окружение каждой запущенной задачи. Загрузка из среды в хранилище (п. 1) лишь делает переменную доступной и для ее экспорта в окружение запускаемых задач нужно использовать соответствующую команду в local.conf или файле конфигурации дистрибутива.
```
     export CCACHE_DIR
```
Побочным эффектом этого является включение переменной в зависимости процесса сборки таких объектов как контрольные суммы setscene. Если это ведет к ненужной пересборке задач, можно внести переменную в «белый список», чтобы код setscene игнорировал зависимость при создании контрольных сумм.

Иногда полезна возможность получать информацию из исходной среды выполнения. Bitbake сохраняет ее в специальной переменной BB_ORIGENV. Эта переменная возвращает объект хранилища данных, который можно запросить стандартными операторами хранилища, такими как getVar(«BB_ORIGENV», False). Этот объект полезен, например, для нахождения исходной переменной DISPLAY.

     origenv = d.getVar("BB_ORIGENV", False)
     bar = origenv.getVar("BAR", False)

Приведенный пример возвращает переменную BAR исходной среды.

3.7. Флаги переменных

Флаги переменных (varflag) помогают управлять функциями и зависимостями задач. BitBake читает и записывает varflag в хранилище, как показано ниже.

variable = d.getVarFlags("variable") self.d.setVarFlags("FOO", {"func": True})

При работе с varflag применяется обычный синтаксис за исключением переопределений. Иными словами, можно добавлять флаги переменных в начале и в конце varflags (параграф 3.1.13. Синтаксис флагов переменных). В BitBake определен набор флагов для заданий и классов. Задачи поддерживают флаги, контролирующие функциональность.

[cleandirs] указывает пустые каталоги, которые нужно создать до запуска задачи. Имеющиеся каталоги удаляются и вместо них создаются пустые.
[depends] управляет зависимостями между задачами (см. DEPENDS и параграф 3.10.5. Зависимости между задачами).
[deptask] управляет зависимостями при сборке (см. DEPENDS и параграф 3.10.2. Зависимости при сборке).
[dirs] указывает каталоги, которые нужно создать до запуска задачи. Имеющиеся каталоги сохраняются. Указанный последним каталог становится текущим для задачи.
[lockfiles] задает один или множество файлов блокировки для работы задачи. Файлом блокировки может владеть лишь одна задача и при попытке блокировать уже заблокированный файл задача будет остановлена до снятия блокировки. Можно применять этот флаг для согласования взаимного исключения задач.
[noexec] значение 1 помечает задачу как пустую и не требующую выполнения. Флаг можно использовать для установки задач в качестве заменителей зависимостей и запрета выполнения ненужных задач в задании.
[nostamp] значение 1 отключает создание BitBake файла штампа для задачи в результате чего задача будет исполняться всякий раз. Любые задачи, зависящие (возможно косвенно) от задачи [nostamp] также будут выполняться, что может удлинить сборку и поэтому требуется осторожная установка флага.
[number_threads] ограничивает для задачи число одновременных потоков. Этот флаг полезен при работе с многоядерными процессами, когда некоторые задачи следует ограничивать по расходу ресурсов. Флаг number_threads работает подобно переменной BB_NUMBER_THREADS,но для одной задачи.

Флаг устанавливается глобально. Например, для ограничения задачи do_fetch двумя потоками можно указать do_fetch[number_threads] = «2». Установка флага в задании (не глобально) может привести к непредсказуемому поведению. Установка значения больше BB_NUMBER_THREADS не будет оказывать влияния.
[postfuncs] содержит список функций для вызова по завершении задачи.
[prefuncs] содержит список функций для вызова перед выполнением задачи.
[rdepends] управляет зависимостями между задачами во время работы (см. переменные RDEPENDS и RRECOMMENDS, а также параграф 3.10.5. Зависимости между задачами).
[rdeptask] (см. переменные RDEPENDS и RRECOMMENDS, а также параграф (см. переменные RDEPENDS и RRECOMMENDS, а также параграф 3.10.3. Зависимости при работе).
[recideptask] при установке вместе с recrdeptask указывает задачу для проверки дополнительных зависимостей.
[recrdeptask] (см. переменные RDEPENDS и RRECOMMENDS, а также параграф (см. переменные RDEPENDS и RRECOMMENDS, а также параграф 3.10.4. Рекурсивные зависимости.
[stamp-extra-info] дополнительные данные, добавляемые в конце штампа задачи. Например, OE использует флаг для машинозависимых задач.
[umask] задает значение для работы задачи.

Некоторые флаги полезны для расчета подписей переменных (см. 2.8. Контрольные суммы (подписи)).

[vardeps] задает разделенный пробелами список дополнительных переменных, добавляемых в зависимости переменных для расчета подписи. Добавление переменной в этот список полезно, например, при ссылке функции на переменную способом, который не позволяет BitBake определить эту ссылку автоматически.
[vardepsexclude] задает разделенный пробелами список переменных, которые следует исключить из зависимостей переменных при расчете подписи.
[vardepvalue] при установке задает BitBake игнорировать действительное значение переменной и применять взамен при расчете подписи указанное значение.
[vardepvalueexclude] задает разделенный символами | список строк для исключения из значения переменной при расчете подписи.

3.8. События

BitBake позволяет устанавливать обработчики событий в файлах заданий и классов. События инициируются в определенных точках во время работы, например, в начале обработки указанного задания (.bb), при запуске указанной задачи, отказе или успешном выполнении задачи и т. п. Цель заключается в упрощении таких действий, как передача по электронной почте сообщений об интересующих событиях. Ниже представлен пример обработчика, печатающего имя события и содержимое переменной FILE.

     addhandler myclass_eventhandler
     python myclass_eventhandler() {
         from bb.event import getName
         print("The name of the Event is %s" % getName(e))
         print("The file we run for is %s" % d.getVar('FILE'))
     }
     myclass_eventhandler[eventmask] = "bb.event.BuildStarted bb.event.BuildCompleted"

В этом примере маска событий (eventmask) установлена так, что обработчик видит лишь события BuildStarted и BuildCompleted. Обработчик вызывается при каждом событии, соответствующем маске. Определена глобальная переменная e, которая представляет текущее событие. Метод getName(e) возвращает имя вызвавшего обработчик события, глобальное хранилище доступно через переменную d. В устаревшем коде для доступа к хранилищу применяли e.data, однако сейчас от этого отказались в пользу d.

Контекст хранилища данных соответствует событию. Например, события BuildStarted и BuildCompleted происходят перед выполнением каких-либо задач и будут находиться в глобальном пространстве имен, где нет метаданных, специфичных для задания. Эти события происходят в основном процессе сборщика/сервера, а не в каком-либо рабочем контексте. Поэтому все изменения в хранилище будут видны другим событиям сборщика/сервера, но не будут доступны за пределами данной сборки или в каком-либо рабочем контексте. События задач происходят в конкретных задачах и поэтому имеют специфичное для задания и задачи содержимое. Эти события происходят в рабочем контексте и отбрасываются по завершении задачи.

Ниже описаны основные события, которые могут происходить при стандартной сборке.

bb.event.ConfigParsed() происходит при анализе базовой конфигурации (bitbake.conf, base.bbclass и все глобальные операторы INHERIT). Можно видеть множество таких событий при разборе базовых конфигураций в каждой сборке или при изменении и повторном анализе конфигурации на сервере. Однако для любого конкретного хранилища данных происходит лишь одно такое событие. Если в хранилище установлен обработчик событий BB_INVALIDCONF,конфигурация анализируется повторно и возникает новое событие, позволяющее метаданным обновить конфигурацию.
bb.event.HeartbeatEvent() происходит регулярно (1 раз в секунду, интервал можно изменить с помощью переменной BB_HEARTBEAT_EVENT). Атрибут time содержит значение time.time() в момент события. Событие полезно для таких действий, как мониторинг состояния системы.
bb.event.ParseStarted() происходит, когда BitBake собирается начать анализ заданий. Атрибут total показывает число заданий, которые BitBake планирует анализировать.
bb.event.ParseProgress() происходит в процессе анализа. Атрибут current указывает число анализируемых заданий, как и атрибут total.
bb.event.ParseCompleted() происходит по завершении анализа. Атрибуты cached, parsed, skipped, virtuals, masked и errors содержат статистику анализа.
bb.event.BuildStarted() происходит при запуске новой сборки. BitBake генерирует множество событий BuildStarted (1 на конфигурацию) при включенной поддержке нескольких конфигураций (multiconfig).
bb.build.TaskStarted() происходит при запуске задачи. Атрибут taskfile указывает задание, которое вызвало задачу, атрибут taskname (имя задачи) включает префикс do_, logfile указывает место записи вывода задачи, а time — время запуска задачи.
bb.build.TaskInvalid() происходит при попытке BitBake выполнить несуществующую задачу.
bb.build.TaskFailedSilent() происходит при отказе задач setscene, когда подробный вывод не нужен.
bb.build.TaskFailed() происходит при отказе обычных задач.
bb.build.TaskSucceeded() происходит при успешном завершении задачи.
bb.event.BuildCompleted() происходит при завершении сборки.
bb.cooker.CookerExit() происходит при выключении сборщика/сервера BitBake и обычно воспринимается пользовательским интерфейсом как сигнал необходимости завершить работу.

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

bb.event.TreeDataPreparationStarted();
bb.event.TreeDataPreparationProgress();
bb.event.TreeDataPreparationCompleted();
bb.event.DepTreeGenerated();
bb.event.CoreBaseFilesFound();
bb.event.ConfigFilePathFound();
bb.event.FilesMatchingFound();
bb.event.ConfigFilesFound();
bb.event.TargetsTreeGenerated().

3.9. Варианты — механизм расширения класса

BitBake поддерживает две функции для создания из одного файла задания нескольких других заданий, которые являются собираемыми. Эти функции включаются переменными BBCLASSEXTEND и BBVERSIONS. Механизм этого расширения класса сильно зависит от реализации. Обычно переменные PROVIDES, PN и DEPENDS в задании классу расширения приходится менять. Примеры можно найти в классах OE-Core native, nativesdk и multilib.

BBCLASSEXTEND содержит список разделенных пробелами классов, которые «расширяют» задание для каждого варианта. Например, BBCLASSEXTEND = «native» будет создавать второй вариант задания с наследованием класса native.
BBVERSIONS позволяет одному заданию собирать несколько вариантов проекта на основе одного файла задания. Можно задать условные метаданные (с помощью OVERRIDES) для одной версии или заданного по условию диапазона версий. Например,
```
     BBVERSIONS = "1.0 2.0 git"
     SRC_URI_git = "git://someurl/somepath.git"

     BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
     SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
```
Имя диапазона по умолчанию соответствует исходной версии задания. Например, в OE файл задания foo_1.0.0+.bb создает принятое по умолчанию имя 1.0.0+. Это полезно, поскольку имя диапазона не только помещается в переопределения, но и доступно метаданным для использования в переменной, определяющей версии базового задания для использования в пути поиска file:// (FILESPATH).

3.10. Зависимости

Для эффективной параллельной работы BitBake обрабатывает зависимости на уровне задач. Зависимости могут существовать между задачами одного или разных заданий. Ниже приведены примеры для обоих случаев.

Внутри задания может потребоваться выполнить do_configure до запуска do_compile.
Задача do_configure может требовать завершения do_populate_sysroot в другом задании для получения библиотек и заголовочных файлов.

В этом разделе описано несколько вариантов объявления зависимостей. Следует помнить, что при любом способе объявления зависимости существуют между задачами.

3.10.1. Зависимости внутри файла .bb

BitBake использует директиву addtask для управления внутренними зависимостями в файле задания. Например, addtask printdate after do_fetch before do_build задает зависимость задачи do_printdate от do_fetch task и зависимость do_build от do_printdate task. Для запуска задачи от нее должна зависеть (напрямую или косвенно) другая задача, запланированная для запуска. Ниже приведено несколько примеров.

Директива addtask mytask перед do_configure заставляет выполнить задачу do_mytask до запуска do_configure. Отметим, что do_mytask будет запускаться лишь при изменении контрольной суммы ввода с момента ее предыдущего запуска. Изменение контрольной суммы ввода do_mytask вызывает также запуск do_configure.
Директива addtask mytask после do_configure сама по себе не ведет к запуску do_mytask, но задачу можно запустить вручную командой bitbake recipe -c mytask. Указание do_mytask в качестве зависимости для другой задачи, запуск которой запланирован, приведет к запуску do_mytask, но в любом случае это произойдет после do_configure.

3.10.2. Зависимости при сборке

BitBake использует переменную DEPENDS для управления зависимостями при сборке. Флаг [deptask] для задач указывает для каждого элемента DEPENDS задачу, которая должна быть выполнена до запуска данной задачи. Например, do_configure[deptask] = «do_populate_sysroot» говорит о необходимости выполнить do_populate_sysroot для каждого элемента DEPENDS перед запуском для него задачи do_configure.

3.10.3. Зависимости при работе

BitBake использует переменные PACKAGES, RDEPENDS и RRECOMMENDS для управления зависимостями при работе. В переменной PACKAGES указаны пакеты, используемые при работе, и каждый из них может иметь зависимости RDEPENDS и RRECOMMENDS. Флаг [rdeptask] для задач указывает для каждой зависимости при работе задачу, которая должна быть выполнена до запуска данной задачи. Например, do_package_qa[rdeptask] = «do_packagedata» указывает, что задача do_packagedata должна быть выполнена для каждого элемента RDEPENDS до запуска do_package_qa.

3.10.4. Рекурсивные зависимости

BitBake использует флаг [recrdeptask] для управления рекурсивными зависимостями задач. BitBake просматривает зависимости текущего задания при сборке и работе, а также зависимости между задачами и затем добавляет зависимости для указанной задачи. После этого BitBake рекурсивно работает с зависимостями задач, продолжая итерации до нахождения и добавления всех зависимостей.

Флаг [recrdeptask] чаще всего применяется в заданиях верхнего уровня, которым приходиться дожидаться завершения той или иной задачи «глобально». Например, в класс image.bbclass включена зависимость do_rootfs[recrdeptask] += «do_packagedata», указывающая, что задачи do_packagedata в текущем задании и во всех доступных (через зависимости) заданиях из задания для образа должны быть выполнены до запуска задачи do_rootfs.

Может возникнуть желание просмотра BitBake не только зависимостей этих задач, но и зависимостей при сборке и работе для зависимых от них задач. В этом случае нужно указать имена задач в виде do_a[recrdeptask] = «do_a do_b».

3.10.5. Зависимости между задачами

BitBake использует флаг [depends] в более общей форме для управления зависимостями между задачами. Эта форма позволяет проверять такие зависимости для конкретных задач вместо проверки данных в DEPENDS. Например, do_patch[depends] = «quilt-native:do_populate_sysroot» задает выполнение задачи do_populate_sysroot для цели quilt-native до запуска do_patch. Флаг [rdepends] работает аналогично но относится к целям в пространстве имен при работе, а не к пространству имен зависимостей при сборке.

3.11. Функции, которые можно вызывать из Python

BitBake предоставляет много функций, которые можно вызывать из функций Python. Они кратко описаны ниже.

3.11.1. Функции для доступа к переменным хранилища данных

Часто нужен доступ к переменных хранилища данных BitBake с использованием функций Python. Хранилище Bitbake имеет интерфейс API для такого доступа. Список поддерживаемых операций приведен ниже.

Операция	Описание
`d.getVar("X", expand)`	Возвращает значение переменной X, преобразуя значение при expand=True. Если переменной X нет, возвращает None.
`d.setVar("X", "value")`	Устанавливает для переменной X значение value.
`d.appendVar("X", "value")`	Добавляет value в конце переменной X. Ведет себя как d.setVar(«X», «value») при отсутствии переменной X.
`d.prependVar("X", "value")`	Добавляет value в начале переменной X. Ведет себя как d.setVar(«X», «value») при отсутствии переменной X.
`d.delVar("X")`	Удаляет переменную X из хранилища при ее наличии.
`d.renameVar("X", "Y")`	Переименовывает переменную X в Y, если она существует.
`d.getVarFlag("X", flag, expand)`	Возвращает значение переменной X, преобразуя значение при expand=True. Если переменной X или флага нет, возвращает None.
`d.setVarFlag("X", flag, "value")`	Устанавливает для флага переменной X значение value.
`d.appendVarFlag("X", flag, "value")`	Добавляет value в конец флагов переменной X. Ведет себя как d.setVarFlag(«X», flag, «value») при отсутствии флага.
`d.prependVarFlag("X", flag, "value")`	Добавляет value в начало флагов переменной X. Ведет себя как d.setVarFlag(«X», flag, «value») при отсутствии флага.
`d.delVarFlag("X", flag)`	Удаляет из хранилища флаг переменной X.
`d.setVarFlags("X", flagsdict)`	Устанавливает флаг, заданный в параметре flagsdict, не сбрасывая имеющийся флаг (как addVarFlags).
`d.getVarFlags("X")`	Возвращает flagsdict флагов переменной X или None, если X нет.
`d.delVarFlags("X")`	Удаляет все флаги переменной X при ее наличии.
`d.expand(expression)`	Преобразует переменную, указанную строкой expression. Ссылки не отсутствующие переменные не меняются. Например, d.expand(«foo ${X}») преобразует строку foo ${X}, если переменной X не существует.

3.11.2. Прочие функции

Другие функции, доступные для вызова из Python можно найти в коде модуля bb (bitbake/lib/bb). Например, bitbake/lib/bb/utils.py включает функции общего пользования bb.utils.contains() и bb.utils.mkdirhier()
из docstrings.

3.12. Контрольные суммы задач и Setscene

BitBake использует контрольные суммы (подписи) с setscene для решения вопроса запуска задач. Здесь рассматривается этот процесс на примере метаданных OE.

Контрольные суммы хранятся в каталоге STAMP. Для проверки контрольных сумм служит команда bitbake-dumpsigs, возвращающая данные подписи в читаемом формате, которые позволяют проверить входные данные, используемые системой сборки OE при генерации подписей. Команда позволяет, например, проверить sigdata задачи do_compile для приложения C (например, bash). Команда также показывает, что переменная CC является частью хэшируемого ввода и изменение этой переменной будет делать штамп недействительным и приведет к перезапуску задачи do_compile.

Ниже перечислены переменные, связанные с контрольными суммами.

BB_HASHCHECK_FUNCTION указывает имя функции, вызываемой setscene для проверки хэш-значений.
BB_SETSCENE_DEPVALID задает функцию, вызываемую BitBake для определения необходимости выполнения зависимости setscene.
BB_SETSCENE_VERIFY_FUNCTION2 задает функцию, вызываемую для проверки списка задач, выполнение которых запланировано до вызова основной задачи.
BB_STAMP_POLICY задает режим сравнения временных меток в штампах.
BB_STAMP_WHITELIST указывает файлы штампов, просматриваемые при политике whitelist.
BB_TASKHASH содержит хэш выполняемой задачи, возвращаемый активированным генератором подписей.
STAMP указывает базовый путь для создания штампов.
STAMPCLEAN задает базовый путь для создания штампов с возможностью использования шаблонов для сопоставления при операциях очистки.

3.13. Поддержка шаблонов в переменных

Поддержка использования шаблонов в переменных зависит от контекста. Например, в некоторых именах переменных и файлов можно ограниченно применять шаблоны % и *, а другие поддерживают синтаксис Python glob, fnmatch или регулярных выражений. Описания переменных, поддерживающих шаблоны, указывают имеющиеся ограничения.

Глава 4. Поддержка загрузки файлов

Модуль сборки (fetch) BitBake является автономной частью библиотечного кода, которая отвечает за извлечение исходных кодов и файлов с удаленных сайтов. Извлечение исходных кодов является одной из важнейших частей сборки, поэтому модуль играет важную роль в BitBake. Современный модуль сборки называется fetch2 и обеспечивает вторую версию API. Исходная версия устарела и была удалена. Все упоминания fetch в документе относятся к fetch2.

4.1. Загрузка (выборка)

Извлечение исходного кода или файлов занимает в BitBake несколько этапов. Код сборщика выполняет 2 основных функции — получение файлов (возможно кэшированных) и их распаковку в указанное место (иногда указанным способом). Получение и распаковка файлов иногда сопровождаются внесением правок (patch). Код, отвечающий за первую часть процесса (выборка) имеет вид

     src_uri = (d.getVar('SRC_URI') or "").split()
     fetcher = bb.fetch2.Fetch(src_uri, d)
     fetcher.download()

Код организует экземпляр класса fetch, использующий список разделенных пробелами URL из переменной SRC_URI для вызова методов загрузки файлов. За организацией экземпляра класса fetch обычно следует код

     rootdir = l.getVar('WORKDIR')
     fetcher.unpack(rootdir)

Этот код распаковывает загруженные файлы в каталоги, указанные WORKDIR.

Для удобства именование в примерах соответствует переменным OE. Для проверки кода в работе следует использовать файл класса OE base.bbclass. Переменные SRC_URI и WORKDIR не заданы жестко в коде сборщика, поскольку методы сбора могут вызываться (и вызываются) с разными именами переменных. В OE, например, код общего состояния (sstate) использует модуль fetch для выборки файлов sstate.

При вызове метода download() BitBake пытается преобразовать URL, просматривая исходные файлы в указанном ниже порядке.

Pre-mirror Sites. BitBake при поиске исходных файлов сначала просматривает PREMIRRORS.
Source URI. Если файлов не найдено, BitBake использует исходную ссылку URL (например, из SRC_URI).
Mirror Sites. При неудаче BitBake обращается к зеркалам, заданным переменной MIRRORS.

Для каждого переданного ему URL сборщик вызывает субмодуль, обрабатывающий данный тип URL. Это может вызывать некоторую путаницу при представлении URL для переменной SRC_URI. Например,

     http://git.yoctoproject.org/git/poky;protocol=git
     git://git.yoctoproject.org/git/poky;protocol=http

В первом случае URL передается сборщику wget, который не понимает протокол git, поэтому корректным будет второй вариант, поскольку сборщик Git понимает, как использовать транспорт HTTP.

Ниже приведено несколько примеров использования «зеркал».

     PREMIRRORS ?= "\
         bzr://.*/.*   http://somemirror.org/sources/ \n \
         cvs://.*/.*   http://somemirror.org/sources/ \n \
         git://.*/.*   http://somemirror.org/sources/ \n \
         hg://.*/.*    http://somemirror.org/sources/ \n \
         osc://.*/.*   http://somemirror.org/sources/ \n \
         p4://.*/.*    http://somemirror.org/sources/ \n \
         svn://.*/.*   http://somemirror.org/sources/ \n"

     MIRRORS =+ "\
         ftp://.*/.*      http://somemirror.org/sources/ \n \
         http://.*/.*     http://somemirror.org/sources/ \n \
         https://.*/.*    http://somemirror.org/sources/ \n"

Следует отметить, что BitBake поддерживает кросс-URL и возможно «зеркало» репозитория Git на сервере HTTP в виде архива (tarball). Именно это делает отображение git:// в прошлом примере. Поскольку доступ через сеть может быть медленным, Bitbake поддерживает кэш загруженных из сети файлов. Все нелокальные исходные файлы (т. е. загруженные из Internet) помещаются в специальный каталог, указанный переменной DL_DIR.

Целостность файлов очень важна для воспроизводимости сборки. Для нелокальных архивов код сборщика может проверять контрольную сумму SHA-256 или MD5, чтобы убедиться в корректности загрузки. Эти контрольные суммы можно задать с помощью переменной SRC_URI и подходящих флагов, как показано ниже.

SRC_URI[md5sum] = "value" SRC_URI[sha256sum] = "value"

Можно также указать контрольные суммы как параметр SRC_URI.

     SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"

При наличии множества URI можно задать контрольные суммы напрямую (см. выше) или путем именования URL.

     SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
     SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d

После загрузки и проверки контрольной суммы в DL_DIR помещается штамп .done, который BitBake использует при последующих сборках для предотвращения ненужной загрузки и новой проверки контрольной суммы. Предполагается, что данные в локальном хранилище не могут повреждаться. Если это не так, могут возникать серьезные проблемы.

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

4.2. Распаковка

Распаковка обычно происходит сразу после загрузки и для всех URL (кроме Git) BitBake применяет один метод. В URL можно указать поведение этапа распаковки, как показано ниже.

unpack управляет распаковкой компонент URL. Используемое по умолчанию значение 1 включает распаковку, а при значении 0 файлы остаются запакованными.
dos применяется для файлов .zip и .jar, задавая символы перевода строки DOS в текстовых файлах.
basepath указывает процессу распаковки вырезание указанных каталогов архива при распаковке.
subdir задает распаковку указанного URL в указанный каталог внутри корневого каталога.

Распаковка может автоматически обрабатывать файлы .Z, .z, .gz, .xz, .zip, .jar, .ipk, .rpm. .srpm, .deb и .bz2, а также различные комбинации расширений архивов.

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

4.3. Сборщики

Префикс URL определяет используемый BitBake субмодуль сборщика. Эти субмодули описаны ниже.

4.3.1. Сборщик локальных файлов (`file://`)

Этот субмодуль обслуживает URL типа file://. Указанное в URL имя файла может быть относительным или абсолютным. Для относительных путей используется переменная FILESPATH как PATH при поиске файлов. Если файл не найден, предполагается, что он доступен в DL_DIR на момент вызова метода download(). Если указан каталог, он распаковывается целиком. Ниже приведены примеры URL с относительным и абсолютным путем.

     SRC_URI = "file://relativefile.patch"
     SRC_URI = "file:///Users/ich/very_important_software"

4.3.2. Сборщик HTTP/FTP wget (`http://`, `ftp://`, `https://`)

Этот сборщик извлекает файлы с серверов web или FTP, используя утилиту wget. Исполняемый файл и параметры задаются переменной FETCHCMD_wget, для которой по умолчанию заданы разумные значения. Сборщик поддерживает параметр downloadfilename, позволяющий указать имя загруженного файла. Это полезно для предотвращения конфликтов имен в DL_DIR. Ниже приведены примеры обрабатываемых сборщиком URL.

     SRC_URI = "http://oe.handhelds.org/not_there.aac"
     SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
     SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"

Разделение параметров URL точкой с запятой может приводить к неоднозначности разбора URL с такими символами.

     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"

В таких URL следует заменять точку с запятой символом &, как показано ниже.

     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47"

Это работает в большинстве случаев, поскольку идентичную трактовку & в URL рекомендует консорциум W3C³. Отметим, что природа URL позволяет задать имя для загруженного файла, как показано ниже.

     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2"

4.3.3. Сборщик CVS `(cvs://`)

Этот субмодуль обслуживает выбор файлов из системы контроля версий CVS. Переменные настройки указаны ниже.

FETCHCMD_cvs — имя исполняемого файла для команды cvs (обычно cvs).
SRCDATE — дата выборки исходного кода CVS. Значение now служит для обновления при каждой сборке.
CVSDIR — задает временное место хранения выборки (обычно DL_DIR/cvs).
CVS_PROXY_HOST — имя, используемое в параметре proxy= для команды cvs.
CVS_PROXY_PORT - номер порта, используемый в параметре proxyport= для команды cvs.

Наряду с обычным для URL указанием имени пользователя и пароля можно указать перечисленные ниже параметры.

«method» задает протокол для связи с сервером CVS (по умолчанию pserver). При установке ext BitBake проверяет параметр rsh и устанавливает CVS_RSH. Можно применять dir для локальных каталогов.
«module» задает выбираемый модуль (обязательно).
«tag» описывает тег CVS TAG, который следует использовать для выбора (по умолчанию пусто).
«date» задает дату. При отсутствии параметра используется SRCDATE из конфигурации. Значение now задает обновление при каждой сборке.
«localdir» служит для переименования модуля (фактически переименовывается каталог для распаковки). Модуль помещается в каталог, указанный относительно CVSDIR.
«rsh» используется вместе с параметром method.
«scmdata» вызывает сохранение метаданных CVS в архиве, который сборщик создает при установке keep. Архив распаковывается в рабочий каталог. По умолчанию метаданные CVS удаляются.
«fullpath» задает нахождение получаемой выборки на уровне модуля (по умолчанию) или ниже.
«norecurse» заставляет сборщик выбирать указанный каталог без рекурсии подкаталогов.
«port» указывает порт для соединения с сервером CVS.

Ниже приведены два примера.

     SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
     SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"

4.3.4. Сборщик SVN (`svn://`)

Этот сборщик извлекает исходный код из системы контроля версий Subversion, используя исполняемый файл, указанный переменной FETCHCMD_svn(по умолчаниюsvn). Временный каталог задает SVNDIR(обычноDL_DIR/svn).

Параметры сборщика перечислены ниже.

«module» задает имя модуля svn для выборки (обязательно).
«path_spec» задает каталог для записи указанного модуля svn.
«protocol» задает используемый протокол (по умолчанию svn). В случае svn+ssh добавляется параметр ssh.
«rev» указывает выбираемый выпуск исходного кода.
«scmdata» оставляет каталоги .svn во время компиляции при установке keep (по умолчанию удаляются).
«ssh» — при установке protocol=svn+ssh может служить для указания программы ssh, применяемой svn.
«transportuser» устанавливает имя пользователя для транспорта при необходимости (по умолчанию пусто). Имя пользователя для транспорта отличается от имени в URL, передаваемом команде subversion.

Ниже приведены примеры использования svn.

     SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667"
     SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh"
     SRC_URI = "svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1"

4.3.5. Сборщик Git (`git://`)

Субмодуль извлекает код из системы управления Git. Сборщик создает клон удаленного репозитория в каталоге GITDIR(обычноDL_DIR/git2). Затем этот клон перемещается на этапе распаковки в рабочий каталог при выборе конкретной ветви. Это делается с использованием вариантов и ссылки для минимизации дублирования данных на диске и ускорения распаковки. Используется исполняемый файл, заданный переменной FETCHCMD_git.

Сборщик поддерживает перечисленные ниже параметры.

«protocol» задает используемый для извлечения файлов протокол (по умолчанию git, если установлено имя хоста). Если имя хоста не задано, применяется протокол file. Можно использовать также http, https, ssh и rsync.
«nocheckout» отменяет проверку исходного кода при распаковке, если задано значение 1. Это применяется при наличии другой программы проверки кода. По умолчанию 0.
«rebaseable» указывает, что для восходящего репозитория Git поддерживается rebase. Следует устанавливать значение 1, если выпуски могут отделяться от ветвей. В таком случае архив зеркала источника выполняется по выпуску, что ведет к потере эффективности. «Перебазирование» восходящего репозитория Git может приводить к исчезновению из него текущего выпуска. Опция напоминает сборщику о необходимости сохранить локальный кэш для использования в будущем. По умолчанию параметр имеет значение 0.
«nobranch» говорит сборщику, что не нужно проверять контрольные суммы SHA, если установлено значение 1 (по умолчанию 0). Следует устанавливать эту опцию в заданиях, указывающих фиксацию (commit), которая действительна для тега, а не для ветви.
«bareclone» указывает сборщику, что нужно клонировать код в целевой каталог без выбора рабочего дерева с предоставлением лишь необработанных (raw) метаданных Git. Предполагается также параметр nocheckout.
«branch» указывает клонируемые ветви дерева Git (по умолчанию master). Число параметров branch соответствует числу параметров name.
«rev» указывает выбираемый выпуск (revision). По умолчанию master.
«tag» указывает выбираемый тег. Для корректного преобразования тегов нужен доступ в сеть, поэтому теги зачастую не применяются. Для Git параметры tag и rev обеспечивают одинаковое поведение.
«subpath» ограничивает выбор конкретным путем в дереве. По умолчанию дерево выбирается целиком.
«destsuffix» указывает путь для размещения выборки (по умолчанию git/).
«usehead» разрешает локальным URL git:// использовать текущую ветвь HEAD в качестве выпуска с AUTOREV. Параметр usehead подразумевает отсутствие ветвления и работает только с протоколом file://.

Примеры URL приведены ниже.

     SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
     SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"

4.3.6. Сборщик субмодулей Git (`gitsm://`)

Этот субмодуль наследует сборщик Git, расширяя его для выборки субмодулей. SRC_URI передается сборщику Git, как описано выше. При переключении между git://иgitsm://требуется очистка задания. Сборщик субмодулейGit не является полной реализацией и имеет ряд известных проблем с некорректным использованием инфраструктуры зеркал. Кроме того, извлекаемые коды субмодулей не видны инфраструктуре лицензирования и архивирования кода.

4.3.7. Сборщик ClearCase (`ccrc://`)

Этот субмодуль извлекает код из репозиториев ClearCase. Для использования сборщика нужно указать корректные значения SRC_URI, SRCREVиPV. Например,

     SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
     SRCREV = "EXAMPLE_CLEARCASE_TAG"
     PV = "${@d.getVar("SRCREV", False).replace("/", "+")}"

Сборщик использует в качестве клиента rcleartool или cleartool. Опции оператора SRC_URI приведены ниже.

vob — имя ClearCase VOB, которое должно иметь в начале символ /. Параметр является обязательным.
module — модуль в выбранном VOB с символом / в начале. Опции module и vob объединяются для создания правила загрузки (load). Например, комбинация vob и module из SRC_URI в приведенном выше примере дает load /example_vob/example_module.
proto указывает протокол http или https.

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

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

При использовании cleartool для входа в систему не требуется дополнительных
действий.
При работе с rcleartool от имени конкретного пользователя нужна команда rcleartool login до запуска сборщика.

4.3.8. Сборщик Perforce (p4://)

Этот субмодуль извлекает код из системы управления Perforce, используя исполняемый файл, указанный переменной FETCHCMD_p4 (по умолчанию p4). Временный рабочий каталог задает переменная P4DIR (по умолчанию DL_DIR/p4).

Для использования сборщика нужно указать корректные значения SRC_URI, SRCREV и PV. Программа p4 способная использовать конфигурационный файл, определенный в переменной окружения P4CONFIG, для указания URL и порта сервера Perforce, имени пользователя и пароля, если они не указаны в задании. При отказе от использования P4CONFIG или явном указании переменных из P4CONFIG можно задать значение P4PORT с URL и номером порта сервера, а также указать имя пользователя и пароль в переменной задания SRC_URI.

Ниже приведен пример с использованием P4CONFIG и выборкой Head Revision.

    SRC_URI = "p4://example-depot/main/source/..."
    SRCREV = "${AUTOREV}"
    PV = "p4-${SRCPV}"
    S = "${WORKDIR}/p4"

В следующем примере задание указывает URL, порт, имя пользователя и пароля для выбора Revision по метке Label.

    P4PORT = "tcp:p4server.example.net:1666"
    SRC_URI = "p4://user:passwd@example-depot/main/source/..."
    SRCREV = "release-1.0"
    PV = "p4-${SRCPV}"
    S = "${WORKDIR}/p4"

В задании всегда следует устанавливать S = "${WORKDIR}/p4".

4.3.9. Сборщик Repo (`repo://`)

Этот сборщик извлекает код из google-repo, сохраняя файлы в каталог REPODIR
(по умолчанию, DL_DIR/repo).

Сборщик поддерживает несколько параметров, указанных ниже.

«protocol» задает протокол для извлечения манифеста репозитория (по умолчанию git).
«branch» указывает ветвь или тег для извлечения файлов (по умолчанию master).
«manifest» указывает файл манифеста (по умолчанию default.xml).

Ниже приведены два примера URL для сборщика.

    SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml"
    SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml"

4.3.10. Другие сборщики

Имеются также субмодули Bazaar (bzr://), Mercurial (hg://), npm (npm://), OSC (osc://), Secure FTP (sftp://), Secure Shell (ssh://), Trees с использованием Git Annex (gitannex://), для которых еще нет документации.

Глава 5. Глоссарий переменных

В этой главе приведены основные переменные, используемые BitBake с описанием их назначения и содержимого.

Переменные, связанные только с BitBake, описание которых ограничивается этим контекстом.
Используемые в BitBake переменные с такими же именами в других системах (например, YP и OE). В этом случае описывается расширенная функциональность.
Отсутствующие в BitBake переменные других систем, которые использует BitBake.

A

ASSUME_PROVIDED

Список имен заданий (значения PN), которые BitBake не пытается собирать, считая их уже собранными. В OpenEmbedded-Core переменная ASSUME_PROVIDED указывает естественные (native) инструменты, которые не нужно собирать. Примером служит git-native, при указании которого используется программа git на хосте сборки.

B

Каталог, в котором BitBake выполняет операции в процессе сборки задания.

BB_ALLOWED_NETWORKS

Список разделенных пробелами хостов, которые сборщику разрешено применять для извлечения исходного кода.

Этот список используется лишь при отсутствии или нулевом значении переменной BB_NO_NETWORK.
Ограниченно поддерживается шаблон *в именах. Например, вместоgit.gnu.org, ftp.gnu.orgи foo.git.gnu.orgможно указатьBB_ALLOWED_NETWORKS = «*.gnu.org». Символ * можно указывать лишь в начале имени перед точкой. Например, можно указать *.foo.bar, но не *aa.foo.bar.
Зеркала, не указанные в списке хостов, пропускаются с записью события в журнал.
Попытка доступа в сеть, не указанную в списке хостов, вызывает отказ.

Полезно использовать BB_ALLOWED_NETWORKS вместе с PREMIRRORS. Добавление нужно хоста в PREMIRRORS обеспечивает извлечение кода из разрешенного источника и позволяет избежать ошибок, связанных с отсутствием хоста в SRC_URI. Это обусловлено тем, что сборщик не пытается использовать хосты из SRC_URIпосле извлечения кода из PREMIRRORS.

BB_CONSOLELOG

Задает путь к журнальному файлу, куда пользовательский интерфейс BitBake записывает вывод сборки.

BB_CURRENTTASK

Имя текущей работающей задачи без префикса do_.

BB_DANGLINGAPPENDS_WARNONLY

Определяет обработку в BitBake ситуаций, когда файл добавления (.bbappend) не имеет соответствующего файла задания (.bb). Это часто возникает при рассинхронизации уровней (например, oe-core встречает версию задания, для которой старого файла уже нет, а другой уровень еще не обновил версию задания). В такой ситуации отказ является самым безопасным решением.

BB_DEFAULT_TASK

Принятая по умолчанию задача для использования в случаях, когда ничего не указано (например, после опции -c). Имя задачи не следует указывать с префиксом do_.

BB_DISKMON_DIRS

Отслеживает доступное пространство и inode при сборке, позволяя контроль по этим параметрам (по умолчанию отключен). Переменная задается в форме BB_DISKMON_DIRS = «<action>,<dir>,<threshold> […]», где

<action>

ABORT — незамедлительное прерывание сборки при превышении порога.

STOPTASKS — остановка сборки после завершения текущих задач в случае превышения порога.

WARN — вывод предупреждения и продолжение сборки. Последующие предупреждения выдаются в соответствии с переменной BB_DISKMON_WARNINTERVAL, которая должна быть определена.

<dir>

Любые каталоги для мониторинга, разделенные пробелами. Если каталоги расположены на одном устройстве, отслеживается лишь первый.

<threshold>

Минимальное пространство на диске или/и минимальное число inode. Можно применять суффиксы G (Гбайт), M (Мбайт), K (Кбайт, принято по умолчанию). Не следует использовать GB, MB или KB.

     BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
     BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
     BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"

Первый пример работает только при установке переменной BB_DISKMON_WARNINTERVAL и заставляет систему сборки немедленно прерывать процесс, если свободное пространство в ${TMPDIR} становится меньше 1 Гбайта или число inode ниже 100 Кбайт. Поскольку указаны 2 каталога, система сборки будет выдавать предупреждение при снижении свободного места в ${SSTATE_DIR} меньше 1 Гбайт или inode меньше 100 Кбайт. Следующие предупреждения будут выдаваться с интервалами, заданными BB_DISKMON_WARNINTERVAL.

Второй пример будет останавливать сборку по завершении задач, когда свободное место в ${TMPDIR} станет меньше 1 Гбайт. Число inode не отслеживается.

Третий пример задает немедленное прерывание сборки при числе свободных inode в ${TMPDIR} меньше 100 Кбайт без отслеживания свободного места в каталоге.

BB_DISKMON_WARNINTERVAL

Задает интервал предупреждений о нехватке места на диске и свободных inode. Для использования переменной нужно задать BB_DISKMON_DIRS с действием WARN. В процессе сборки при снижении свободного места будут выдаваться предупреждения с заданным интервалом. Если при установке BB_DISKMON_DIRS = «WARN» интервал не указан, используется BB_DISKMON_WARNINTERVAL = «50M,5K». При задании переменной в файле конфигурации применяется форма BB_DISKMON_WARNINTERVAL = «<disk_space_interval>,<disk_inode_interval>».

<disk_space_interval>

Интервал свободного пространства в G (Гбайт), M (Мбайт) или K (Кбайт). Не используйте GB, MB или KB.

<disk_inode_interval>

Интервал свободных inode в G (Гбайт), M (Мбайт) или K (Кбайт). Не используйте GB, MB или KB.

     BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
     BB_DISKMON_WARNINTERVAL = "50M,5K"

Эти переменные заставляют BitBake выдавать предупреждения каждый раз, когда свободное место в каталоге ${SSTATE_DIR} снижается на50 Мбайт или число свободных inode — на 5 Кбайт. Предупреждения будут выдаваться после того, как свободное место станет меньше 1 Гбайт или число свободных inode — меньше 100 Кбайт.

BB_ENV_WHITELIST

Задает внутренний список переменных, которые пропускаются из внешней среды в хранилище данных BitBake. Если переменная не задана (принято по умолчанию), пропускаются переменные BBPATH, BB_PRESERVE_ENV, BB_ENV_WHITELISTиBB_ENV_EXTRAWHITE. Для работы переменной ее нужно установить во внешней среде.

BB_ENV_EXTRAWHITE

Задает список дополнительных переменных для пропуска из внешней среды в хранилище BitBake. Этот список дополняет BB_ENV_WHITELIST. Для работы переменной ее нужно установить во внешней среде.

BB_FETCH_PREMIRRORONLY

Значение 1 заставляет модуль сборщика BitBake искать файлы только по переменной PREMIRRORS (без SRC_URI и MIRRORS).

BB_FILENAME

Имя файла задания, владеющего текущей выполняемой задачей. Например, при выполнении задачи do_fetch в задании my-recipe.bb переменная BB_FILENAME будет содержать /foo/path/my-recipe.bb.

BB_GENERATE_MIRROR_TARBALLS

Заставляет помещать архивы репозиториев Git (включая метаданные Git) в каталог DL_DIR. Из соображений производительности по умолчанию создание и сохранение архивов отключено в BitBake. Для включения нужно задать BB_GENERATE_MIRROR_TARBALLS = «1».

BB_HASHCONFIG_WHITELIST

Указывает переменные, исключаемые из расчета контрольной суммы базовой конфигурации, используемой для решения вопроса об использовании кэша. Одним из способов решения вопроса о повторном использовании метаданных является контрольная сумма переменных в хранилище базовой конфигурации BitBake. Есть переменные, которые обычно не нужно учитывать в контрольной сумме. Например, TIME и DATE меняются постоянно, поэтому при их учете BitBake просто не сможет повторно использовать кэш.

BB_HASHBASE_WHITELIST

Указывает переменные, исключаемые из данных контрольных сумм и зависимостей. Типичным примером такой переменной служит путь к сборке. Вывод BitBake не должен зависеть (и обычно не зависит) от каталога сборки.

BB_HASHCHECK_FUNCTION

Имя функции, вызываемой на этапе setscene при выполнении задачи для проверки списка хэш-значений задач. Функция возвращает список задач для выполнения. На этом этапе цель заключается в быстрой проверке работы данной функции setscene. Проще проверить функции по списку за один проход, нежели вызывать множество отдельных задач. Возвращаемый список может быть не совсем точным и данная задача setscene может потом завершиться отказом. Повышение точности возвращаемых данных обеспечивает рост эффективности сборки.

BB_INVALIDCONF

Используется с событием ConfigParsed для запуска повторного анализа базовых метаданных (т. е. всех заданий). Событие ConfigParsed может устанавливать переменную для повтора анализа. Нужно быть осторожным, чтобы не создать петлю.

BB_LOGFMT

Задает имя для журнальных файлов, сохраняемых в ${T}. По умолчанию переменная не задана и файлы именуются в форме log.{task}.{pid}.

BB_NICE_LEVEL

Позволяет BitBake работать с указанным приоритетом (уровень nice). Системные полномочия обычно позволяют BitBake понижать свой приоритет, но не повышать его снова. См. также описание BB_TASK_NICE_LEVEL.

BB_NO_NETWORK

Отключает доступ в сеть модулям выборки BitBake. В этом случае попытка доступа в сеть будет вызвать ошибку. Запрет полезен для тестирования зеркал исходного кода, сборки без доступа в Internet и при работе за некоторыми межсетевыми экранами.

BB_NUMBER_THREADS

Максимальное число задач, которые BitBake следует запускать параллельно. В системах с большим числом процессорных ядер значением этой переменной разумно устанавливать удвоенное число ядер.

BB_NUMBER_PARSE_THREADS

Задает число потоков, используемых BitBake при анализе. По умолчанию совпадает с числом процессорных ядер.

BB_ORIGENV

Содержит копию исходного внешнего окружения, в котором работает BitBake. Копия делается до применения фильтров хранилища BitBake. Эта переменная является обычным объектом хранилища данных.

BB_PRESERVE_ENV

Отключает «белый список» и пропускает все переменные из внешней среды в хранилище BitBake. Чтобы переменная работала, ее нужно установить во внешней среде.

BB_RUNFMT

Указывает имя исполняемых сценариев (файлы run), сохраняемых в ${T}. По умолчанию переменная не задана и файлы именуются в форме run.{task}.{pid}.

BB_RUNTASK

Имя выполняемой в данный момент задачи с префиксом do_.

BB_SCHEDULER

Задает планировщик, используемый BitBake и может принимать одно из трех значений:

basic — базовая модель с числовым упорядочением задач по мере из разбора;
speed — сначала выполняются задачи, от которых зависит больше других задач (принято по умолчанию);
completion — планировщик пытается завершить данное задание после начала его сборки.

BB_SCHEDULERS

Указывает настраиваемый планировщик для импорта. Эти планировщики должны выводиться из класса RunQueueScheduler. Выбор планировщика определяется переменной BB_SCHEDULER.

BB_SETSCENE_DEPVALID

Задает функцию, вызываемую BitBake для определения необходимости выполнения зависимости setscene. При запуске задачи setscene нужно знать, какие из ее зависимостей также следует запускать. Выполнение зависимостей существенно зависит от метаданных. Заданная переменной функция возвращает True или False.

BB_SETSCENE_VERIFY_FUNCTION2

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

BB_SIGNATURE_EXCLUDE_FLAGS

Список флагов переменных (varflag), которые можно безопасно исключить из контрольных сумм и данных зависимостей для ключей в хранилище. При генерации контрольных сумм и данных зависимостей для ключей установленные флаги ключа обычно учитываются (см. раздел 3.7. Флаги переменных).

BB_SIGNATURE_HANDLER

Задает имя обработчика подписей, используемого BitBake, который определяет способ создания и обработки файлов штампов, встраивания в них подписей и создания этих подписей. Можно добавить обработчик путем внедрения класса, выведенного из SignatureGenerator, в глобальное пространство имен.

BB_SRCREV_POLICY

Определяет поведение сборщика при взаимодействии с системами управления версиями и динамическими выпусками кода. Переменная полезна при работе без сети. Поддерживается два варианта:

cache — сохраняется полученное ранее значение вместо запроса системы управления версиями;
clear — система управления версиями запрашивается каждый раз (без кэширования, принято по умолчанию).

BB_STAMP_POLICY

Задает режим сравнения временных меток в файлах штампов:

perfile — сравниваются только метки в одном задании (принято по умолчанию);
full — сравниваются метки для всех зависимостей;
whitelist — похоже на full, но метки сравниваются для заданий из переменной BB_STAMP_WHITELIST.

Правила для штампов по большей части устарели с введением задач setscene.

BB_STAMP_WHITELIST

Список файлов, для которых временные метки штампов сравниваются в режиме whitelist (BB_STAMP_POLICY).

BB_STRICT_CHECKSUM

Задает более строгую проверку контрольных сумм для нелокальных URL. BitBake будет возвращать ошибку при обнаружении нелокального URL, для которого не задана хотя бы одна контрольная сумма.

BB_TASK_IONICE_LEVEL

Позволяет настроить приоритет ввода-вывода (I/O) для задачи. При тестировании Autobuilder могут возникать случайные ошибки связанные с насыщением I/O во время тайм-аутов QEMU, которые можно исключить настройкой приоритетов. Переменная работает подобно BB_TASK_NICE_LEVEL, но относится только к операциям I/O.

BB_TASK_IONICE_LEVEL = "class.prio"

Для class по умолчанию используется значение 2 (best effort), но можно задать 1 (realtime) или 3 (idle). Для режима realtime требуются полномочия superuser. Для prio можно использовать значения от 0 (высший приоритет) до 7 (низший), по умолчанию установлено 4. Для установки prio не требуется особых полномочий.

Для работы настроек приоритета I/O нужна поддержка планировщика CFQ4 для блочного устройства. Для выбора планировщика служит приведенная ниже команда, где вместо device нужно указать реальное устройство (sda, sdb).

$ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler

BB_TASK_NICE_LEVEL

Позволяет конкретной задаче изменить свой приоритет (уровень nice). Эту переменную можно применять с переопределениями задач для установки приоритета конкретных задач. Например, в Yocto Project autobuilder эмуляция QEMU в образах получает более высокий приоритет, нежели задачи сборки, чтобы не возникало тайм-аутов на загруженных системах.

BB_TASKHASH

В исполняемой задаче эта переменная содержит хэш задачи, возвращаемый активным генератором подписей.

BB_VERBOSE_LOGS

Задает повышенную детализацию вывода BitBake при сборке, включая команды echo и вывод shell-сценариев.

BB_WORKERCONTEXT

Указывает выполнение задачи в текущем контексте (1). Значение не устанавливается, если задача находится в контексте сервера в процессе синтаксического анализа или обработки события.

BBCLASSEXTEND

Позволяет расширить задание для сборки вариантов программы. Такими вариантами для заданий из метаданных OpenEmbedded-Core являются native, такие как quilt-native(копияQuilt для работы в системе сборки), cross, такие как gcc-cross(компилятор для машину сборки, создающий двоичные файлы для целевой MACHINE),nativesdk, предназначенные для SDK вместо MACHINE,иmulitlibs в форме multilib:multilib_name. Сборка разных вариантов задания с минимальным объемом кода обычно так же проста, как добавление переменной в задание. Ниже приведены два примера вариантов из метаданных OpenEmbedded-Core.

BBCLASSEXTEND =+ "native nativesdk"
     BBCLASSEXTEND =+ "multilib:multilib_name"

Механизм BBCLASSEXTEND создает варианты задания, переписывая значения переменных и применяя переопределения, такие как _class-native. Например, для генерации native-версии задания в переменной DEPENDS заменяется foo на foo-native. Даже при использовании BBCLASSEXTEND задание собирается в один прием. Однократный разбор вносит некоторые ограничения, например, невозможно включить разные файлы в зависимости от варианта, поскольку операторы include обрабатываются при анализе задания.

BBDEBUG

Устанавливает уровень отладочного вывода BitBake, который можно увеличить опцией -D. Для работы переменной ее нужно задать во внешней среде.

BBFILE_COLLECTIONS

Список имен настроенных уровней для поиска других переменных BBFILE_*. Обычно каждый уровень добавляет свое имя в конце этой переменной в файле conf/layer.conf.

BBFILE_PATTERN

Переменная, преобразуемая для сопоставления с файлами из BBFILES в отдельном уровне. Переменная задается в файле conf/layer.conf и должна иметь имя уровня как суффикс (например, BBFILE_PATTERN_emenlow).

BBFILE_PRIORITY

Задает приоритет файлов задания в каждом уровне. Это полезно в ситуациях, где одно задание присутствует на нескольких уровнях. Переменная позволяет приоритизировать уровни с одинаковыми заданиями. Заданный переменной приоритет сохраняется независимо от версии задания (PV). Например, уровень может включать файл с большим значением PV, но меньшим приоритетом в BBFILE_PRIORITY и не будет выбран в результате. Большее значение переменной обеспечивает более высокий приоритет. Если переменная не задана, она устанавливается на основе зависимостей уровня (переменная LAYERDEPENDS). Если приоритет не задан для уровня без зависимостей, значение определяется минимальным имеющимся приоритетом +1 (или 1, если приоритетов не задано). Для просмотра настроенных уровней с их приоритетами служит команда bitbake-layers show-layers.

BBFILES

Разделенный пробелами список файлов заданий, используемых BitBake для сборки. При указании файлов можно использовать синтаксис Python glob.

BBINCLUDED

Разделенный пробелами список файлов, включенных анализатором BitBake при разборе текущего файла.

BBINCLUDELOGS

Включает вывод журнала задачи при сообщении об отказе задачи.

BBINCLUDELOGS_LINES

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

BBLAYERS

Список уровней, включенных в сборку. Задается в файле bblayers.conf внутри каталога сборки. Например,

     BBLAYERS = " \
       /home/scottrif/poky/meta \
       /home/scottrif/poky/meta-yocto \
       /home/scottrif/poky/meta-yocto-bsp \
       /home/scottrif/poky/meta-mykernel \
       "

Здесь заданы 4 уровня, один из которых (meta-mykernel) является пользовательским.

BBLAYERS_FETCH_DIR

Указывает базовое местоположение уровней. Переменная используется с командой bitbake-layers layerindex-fetch.

BBMASK

Управляет исключением файлов заданий и дополнений из обработки BitBake, «пряча» ненужные файлы. BitBake игнорирует задания и дополнения, соответствующие выражениям маски. Значение переменной передается компилятору регулярных выражений Python, в маске применяется синтаксис Python Regular Expression (re). Сравнение выполняется для полных путей к файлам. Приведенный ниже пример обеспечивает игнорирование BitBake всех заданий и дополнений в каталоге meta-ti/recipes-misc/.

     BBMASK = "meta-ti/recipes-misc/"

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

     BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
     BBMASK += "/meta-oe/recipes-support/"
     BBMASK += "/meta-foo/.*/openldap"
     BBMASK += "opencv.*\.bbappend"
     BBMASK += "lzma"

Для исключения каталога следует указывать символ / в конце имени.

BBMULTICONFIG

Позволяет BitBake выполнить сборку со множеством конфигураций и указывает каждую конфигурацию (multiconfig). С помощью этой переменной можно задать BitBake сборку нескольких целей, каждая из которых имеет свою конфигурацию. Переменная задается в файле conf/local.conf, например, BBMULTIFONFIG = «configA configB configC». Каждый конфигурационный файл должен размещаться в каталоге сборки внутри каталога conf/multiconfig (например, build_directory/conf/multiconfig/configA.conf). Использование переменной в среде с поддержкой сборки нескольких конфигураций описано в параграфе 1.5.2.5. Сборка с несколькими конфигурациями.

BBPATH

Используется BitBake для поиска файлов классов (.bbclass) и конфигурации (.conf) подобно переменной окружения PATH. При запуске BitBake извне сборочного каталога нужно убедиться, что BBPATH указывает каталог сборки. Переменная устанавливается во внешнем окружении до запуска BitBake, как показано ниже.

$ BBPATH="build_directory" $ export BBPATH $ bitbake target

BBSERVER

Указывает сервер, на котором работает BitBake в режиме memory-resident, и работает только в этом случае.

BBTARGETS

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

BBVERSIONS

Позволяет собрать несколько версий программы по одному файлу задания. Можно также указать дополнительные метаданные с использованием механизма переопределения (OVERRIDES) для одной версии или именованного набора версий (см. раздел 3.9. Варианты — механизм расширения класса).

BITBAKE_UI

Служит для указания модуля UI, используемого BitBake (как опция -u в команде). Для работы переменной ее нужно установить во внешней среде.

BUILDNAME

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

BZRDIR

Каталог, в котором сохраняются выбранные файлы Bazaar.

C

CACHE

Каталог, используемый BitBake для кэширования метаданных, которые не нужно разбирать при каждом запуске.

CVSDIR

Каталог, в котром сохраняются выбранные файлы CVS.

D

DEFAULT_PREFERENCE

Задает незначительное смещение базы приоритета для выбора задания. Обычно для этой переменной устанавливается значение «-1» в заданиях для находящихся в разработке версий. Такое использование переменной ведет к сборке по умолчанию стабильной версии задания при отсутствии PREFERRED_VERSION для сборки разрабатываемой версии.

Смещение в DEFAULT_PREFERENCE невелико и переопределяется значением BBFILE_PRIORITY, если эта переменная различается между двумя уровнями с разными версиями одного задания.

DEPENDS

Список зависимостей при сборке задания (другие задания).

DESCRIPTION

Длинное описание задания.

DL_DIR

Центральный каталог загрузки, используемый процессом сборки для хранения загруженных файлов. По умолчанию DL_DIR принимает любые файлы для «зеркалирования», кроме репозиториев Git. Если нужно архивировать файлы репозиториев Git, следует использовать переменную BB_GENERATE_MIRROR_TARBALLS.

E

EXCLUDE_FROM_WORLD

Предписывает BitBake исключить задание из сборки world (bitbake world), когда BitBake находит, анализирует и собирает все задания, найденные в каждом уровне, указанном в файле bblayers.conf. Для исключения задания следует указать значение 1 для этой переменной в задании. Указанные в переменной задания могут сохраняться в сборке world для выполнения зависимостей других заданий, т. е. добавление задания в переменную исключает лишь его явное включение в список заданий сборки world.

F

FAKEROOT

Содержит команду, используемую при работе сценариев оболочки в среде fakeroot. Переменная устарела и заменена переменными FAKEROOT*, описанными
ниже.

FAKEROOTBASEENV

Список переменных среды, которые нужно установить при выполнении команды, заданной в FAKEROOTCMD, которая запускает процесс bitbake-worker в среде fakeroot.

FAKEROOTCMD

Команда, запускающая процесс bitbake-worker в среде fakeroot.

FAKEROOTDIRS

Список каталогов, создаваемых перед запуском задачи в среде fakeroot.

FAKEROOTENV

Список переменных окружения, устанавливаемых при запуске задачи в среде fakeroot (см. FAKEROOTBASEENV).

FAKEROOTNOENV

Список переменных окружения, устанавливаемых при запуске задачи вне среды fakeroot (см. FAKEROOTENV).

FETCHCMD

Определяет команду, выполняемую сборщиком BitBake при операции извлечения кода. При использовании переменной требуется задавать суффикс переопределения (например, FETCHCMD_git или FETCHCMD_svn).

FILE

Указывает текущий файл. BitBake устанавливает переменную в процессе анализа, а также при выполнении задания для идентификации файла.

FILESPATH

Указывает каталоги, используемые BitBake при поиске правок (patch) и файлов. Сборщик local использует эти каталоги при обработке URL file://. Переменная похожа на переменную среды PATH и содержит разделенные двоеточиями каталоги, которые просматриваются слева направо.

G

GITDIR

Каталог для хранения локальной копии репозитория Git при его клонировании.

H

HGDIR

Каталог для хранения файлов, выбранных из Mercurial.

HOMEPAGE

Web-сайт с информацией о программе, собираемой заданием.

I

INHERIT

Задает классы с глобальным наследованием. Анонимные функции классов не выполняются для базовой конфигурации и отдельных заданий, система сборки OE игнорирует изменения INHERIT в отдельных заданиях (см.

параграф 3.4.5. Конфигурационная директива INHERIT).

L

LAYERDEPENDS

Список разделенных пробелами уровней, от которых зависит задание. Можно также указать конкретную версию уровня для зависимости, добавив ее к имени после двоеточия (например, anotherlayer:3 будет сравниваться с LAYERVERSION_anotherlayer). BitBake возвращает ошибку при невыполнении зависимости или несовпадении версии. Переменная задается в файле conf/layer.confс использованием имени задания в качестве суффикса(например, LAYERDEPENDS_mylayer).

LAYERDIR

При указании в layer.conf задает путь к текущему уровню. Переменная недоступна вне layer.conf и ссылки на нее преобразуются сразу же при анализе файла.

LAYERDIR_RE

При указании в layer.conf задает путь к текущему уровню с экранированием (escape) для использования в регулярном выражении (BBFILE_PATTERN). Переменная недоступна вне layer.conf и ссылки на нее преобразуются сразу же при анализе файла.

LAYERVERSION

Может задавать версию уровня одним числом. Переменную можно использовать в LAYERDEPENDS для другого уровня при указании зависимости от конкретной версии. Переменная задается в conf/layer.conf и должна содержать имя конкретного уровня в качестве суффикса (например, LAYERDEPENDS_mylayer).

LICENSE

Список лицензий для задания.

M

MIRRORS

Задает дополнительные пути для поиска исходных кодов. Система сборки сначала проверяет каталог загрузок, затем места, указанные в PREMIRRORS, восходящий репозиторий и зеркала, указанные в MIRRORS.

MULTI_PROVIDER_WHITELIST

Позволяет отключить предупреждения BitBake при сборке двух отдельных заданий с одинаковым выводом. Обычно Bitbake выдает такие предупреждения, но в некоторых случаях подобная сборка имеет смысл (в частности, для пространства имен virtual/*). Переменная содержит список провайдеров (например, имена заданий, virtual/kernel и т. п.).

O

OVERRIDES

BitBake использует OVERRIDES для управления переопределениями переменных после разбора заданий и файлов конфигурации. Ниже приведен простой пример переопределения на основе архитектуры машины.

     OVERRIDES = "arm:x86:mips:powerpc"

Дополнительная информация приведена в разделе 3.3. Синтаксис условий.

P

P4DIR

Каталог с локальной копией хранилища Perforce при его выборке.

PACKAGES

Список пакетов, создаваемых заданием.

PACKAGES_DYNAMIC

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

Эпоха для задания (по умолчанию не задана). Переменная применяется для обновления при изменении схемы версий несовместимым со старыми версиями способом.

PERSISTENT_DIR

Каталог, используемый BitBake для хранения данных между сборками. В частности, это данные, используемые BitBake API, а также сервером и службой PR.

Имя задания или пакета с номером версии и выпуска (например, eglibc-2.13-r20+svnr15508/ или bash-4.2-r1/).

Имя задания.

Выпуск (revision) задания.

PREFERRED_PROVIDER

Определяет предпочтительное задание, если несколько заданий предоставляют один и тот же элемент. Следует всегда применять эту переменную с суффиксом из имени предоставляемого задания (значение PN из задания), для которого указывается предпочтение. Например,

     PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
     PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
     PREFERRED_PROVIDER_virtual/libgl ?= "mesa"

PREFERRED_PROVIDERS

Определяет предпочтительное задание, если несколько заданий предоставляют один и тот же элемент. Функционально идентична переменной PREFERRED_PROVIDER,однако позволяет задать предпочтения для нескольких ситуаций в формеPREFERRED_PROVIDERS = «xxx:yyy aaa:bbb …». Это служит удобной заменой для

     PREFERRED_PROVIDER_xxx = "yyy"
     PREFERRED_PROVIDER_aaa = "bbb"

PREFERRED_VERSION

При наличии нескольких версий задания эта переменная определяет предпочтительное. Следует всегда применять эту переменную с суффиксом из имени задания (значение PN из задания) и устанавливать в задании нужное значение PV. Переменная PREFERRED_VERSION поддерживает ограниченное использование шаблона %,которому могут соответствовать любые символы. Например,

     PREFERRED_VERSION_python = "2.7.3"
     PREFERRED_VERSION_linux-yocto = "4.12%"

Символ %можно указывать только последним в строке.

PREMIRRORS

Указывает дополнительные пути получения исходного кода для BitBake. При поиске кода система сборки сначала проверяет локальные источники в каталоге загрузки. Если там ничего не найдено, проверяются места, указанные в переменной PREMIRRORS, восходящий источник, а затем MIRRORS в указанном порядке.

Обычно в переменной указываются предпочтительный сервер, например

     PREMIRRORS_prepend = "\
     git://.*/.* http://www.yoctoproject.org/sources/ \n \
     ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
     http://.*/.* http://www.yoctoproject.org/sources/ \n \
     https://.*/.* http://www.yoctoproject.org/sources/ \n"

В результате система сборки будет перехватывать запросы Git, FTP, HTTP, HTTPS и направлять на зеркало http://. Можно указать URL file:// для загрузки с локальных или общих сетевых дисков.

PROVIDES

Список псевдонимов, под которыми может быть известно определенное задание. По умолчанию значение PN для задания неявно включено в этот список. Если задание содержит PROVIDES, дополнительные псевдонимы являются синонимами задания
и могут применяться для соблюдения зависимостей других заданий во время сборки, указанных в DEPENDS. Например, в файле libav_0.8.11.bb указано PROVIDES += «libpostproc» и в результате задание libav будет известно также под именем libpostproc.

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

Обычно виртуальные цели имеют имена вида virtual/function (например, virtual/kernel), где символ / является частью имени и не имеет синтаксического значения.

PRSERV_HOST

Хост и порт сетевой службы PR, например PRSERV_HOST = «localhost:0». Эту переменную нужно устанавливать при автоматическом запуске сервиса PR. В переменной PRSERV_HOST можно указать удаленную службу PR.

Версия задания.

R

RDEPENDS

Список зависимостей пакета при работе (другие пакеты), которые должны быть установлены. Если пакет не найден при сборке, возникает ошибка. Поскольку переменная RDEPENDS применяется к собираемым пакетам, ее всегда следует связывать с именем пакета. Предположим, например, сборку пакета разработки, зависящего от perl. В этом случае следует указать RDEPENDS_${PN}-dev += «perl». BitBake поддерживает указание версии в зависимостях. Хотя синтаксис зависит от формата пакетов, эта зависимость скрывается BitBake и в переменных RDEPENDS применяется синтаксис RDEPENDS_${PN} = «package (operator version)», где оператором может быть =, <, >, <=, >=. Например, для указания зависимости от пакета foo версии не ниже 1.2 можно использовать RDEPENDS_${PN} = «foo (>= 1.2)». Зависимости при сборке рассмотрены в описании переменной DEPENDS.

REPODIR

Каталог, в котором хранится локальная копия google-repo при синхронизации.

RPROVIDES

Список псевдонимов, которые имеет пакет. Псевдонимы полезны для выполнения зависимостей при работе пакетов как во время сборки, так и на целевой платформе (RDEPENDS). Как во всех переменных управления пакетами должно применяться переопределение по имени пакета, например, RPROVIDES_${PN} = «widget-abi-2»

RRECOMMENDS

Список пакетов, расширяющих применимость собираемого пакета, который не зависит напрямую от этих пакетов при сборке, но они нужны для расширения возможностей. Для задания зависимостей при работе служит переменная RDEPENDS. BitBake поддерживает указание версии в рекомендациях. Хотя синтаксис зависит от формата пакетов, эта зависимость скрывается BitBake и в переменных RRECOMMENDS применяется синтаксис RRECOMMENDS_${PN} = «package (operator version)» , где оператором может быть =, <, >, <=, >=. Например, для рекомендации пакета версии не ниже 1.2 можно использовать RRECOMMENDS_${PN} = «foo (>= 1.2)».

S

SECTION

Категория, к которой следует отнести пакет.

SRC_URI

Список исходных файлов (локальных или удаленных). Переменная указывает BitBake исходные файлы для сборки и способ их получения. Например, если заданию или файлу дополнения нужно извлечь архив из Internet, используется запись SRC_URI, указывающая этот архив. Если же нужно извлечь архив и добавить пользовательские файлы, переменная SRC_URI должна указывать все источники. Ниже перечислены поддерживаемые протоколы.

file:// — выборка файлов, обычно сопровождаемых метаданными, из локальных каталогов. Пути указываются относительно переменной FILESPATH.
bzr:// — выборка из репозитория Bazaar.
git:// — выборка из репозитория Git.
osc:// — выборка из репозитория OSC (OpenSUSE Build service).
repo:// — выборка из репозитория repo (Git).
http:// — выборка из Internet по протоколу HTTP.
https:// — выборка из Internet по протоколу HTTPS.
ftp:// — выборка из Internet по протоколу FTP.
cvs:// — выборка из репозитория CVS.
hg:// — выборка из репозитория Mercurial (hg).
p4:// — выборка из репозитория Perforce (p4).
ssh:// — выборка по протоколу ssh.
svn:// — выборка из репозитория Subversion (svn).

Следует также отметить ряд опций:

unpack — управляет распаковкой архивов (включена по умолчанию);
subdir — указывает каталог для размещения файла ии распаковки архива (полезно для архивов без структуры каталогов);
name — указывает имя, используемое для привязки к контрольной сумме SRC_URI, когда в SRC_URI указно несколько файлов.
downloadfilename — имя для сохранения загруженного файла.

SRCDATE

Дата исходного кода, использованного для сборки, применяемая лишь для источников, полученных из SCM.

SRCREV

Выпуск (revision) исходного кода, использованного для сборки, применяемый лишь для источников, полученных из Subversion, Git, Mercurial и Bazaar. Если нужно собрать конкретный выпуск и избежать запроса к удаленному репозиторию при каждом разборе задания, следует указать в переменной полный идентификатор, а не просто тег.

SRCREV_FORMAT

Помогает создать корректное значение SRCREV при использовании множества управляемых источниками URL в переменной SRC_URI. Каждой компоненте SRC_URI дается имя, указываемое в SRCREV_FORMAT. Например, URL можно назвать machine и meta, а переменная SRCREV_FORMAT может иметь вид machine_meta и в эти имена будут подставляться версии SCM. При необходимости можно добавлять заполнитель AUTOINC в начале возвращаемой строки.

STAMP

Задает базовый путь для файлов штампов задания. Путь к реальному файлу штампа создается преобразованием этой строки с добавлением в конце дополнительной информации.

STAMPCLEAN

Задает базовый путь для файлов штампов задания. В отличие от STAMP, переменная STAMPCLEAN может включать шаблоны для сопоставления с диапазоном файлов, которые должна удалить операция очистки, используемая BitBake для удаления старых штампов.

SUMMARY

Краткое описание задания (до 72 символов).

SVNDIR

Каталог для хранения выбранных файлов Subversion.

T

Указывает каталог, где BitBake хранит временные файлы (в основном сценарии и журналы вывода) при сборке конкретного задания.

TOPDIR

Указывает каталог сборки (BitBake автоматически устанавливает переменную).

Приложение A. Пример Hello World

A.1. BitBake Hello World

В этом простом примере показано, как создать новый проект и подходящие метаданные в контексте BitBake.

A.2. Получение BitBake

Информация о получении и установке приведена в разделе 1.4. Получение BitBake. Каталог BitBake имеет вид

     $ ls -al
     total 100
     drwxrwxr-x. 9 wmat wmat  4096 Jan 31 13:44 .
     drwxrwxr-x. 3 wmat wmat  4096 Feb  4 10:45 ..
     -rw-rw-r--. 1 wmat wmat   365 Nov 26 04:55 AUTHORS
     drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 bin
     drwxrwxr-x. 4 wmat wmat  4096 Jan 31 13:44 build
     -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
     drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 classes
     drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 conf
     drwxrwxr-x. 3 wmat wmat  4096 Nov 26 04:55 contrib
     -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
     drwxrwxr-x. 3 wmat wmat  4096 Nov 26 04:55 doc
     -rw-rw-r--. 1 wmat wmat    69 Nov 26 04:55 .gitignore
     -rw-rw-r--. 1 wmat wmat   849 Nov 26 04:55 HEADER
     drwxrwxr-x. 5 wmat wmat  4096 Jan 31 13:44 lib
     -rw-rw-r--. 1 wmat wmat   195 Nov 26 04:55 MANIFEST.in
     -rw-rw-r--. 1 wmat wmat  2887 Nov 26 04:55 TODO

A.3. Организация среды BitBake

Сначала нужно проверить возможность запуска BitBake. В каталоге BitBake введите команду

     $ ./bin/bitbake --version
     BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0

На консоль будет выведена информация о версии, как показано выше.

Рекомендуется запускать BitBake из каталога программы, но можно также включить каталог BitBake в переменную PATH, предварительно посмотрев текущее значение с помощью команды echo $PATH. Затем следует добавить в начало этой переменной каталог BitBake. Например, для программы в каталоге /home/scott-lenovo/bitbake/bin следует использовать команду export PATH=/home/scott-lenovo/bitbake/bin:$PATH. После этого можно использовать команду bitbake из любого каталога.

A.4. Пример Hello World

Целью примера Hello World является иллюстрация применения концепций задач и уровней. Поскольку именно так работают OE и YP, использующие BitBake, это будет хорошей отправной точкой для начала работы. Дополнительную информацию можно получить из почтовой конференции http://lists.openembedded.org/mailman/listinfo/bitbake-devel.

Пример Hello World описывается ниже.

Создание каталога для проекта под названием hello в домашнем каталоге.
```
     $ mkdir ~/hello
     $ cd ~/hello 
```
Этот BitBake будет использовать для работы и в нем же можно хранить метаданные, нужные для BitBake.

Запуск Bitbake.

     $ bitbake
     The BBPATH variable is not set and bitbake did not
     find a conf/bblayers.conf file in the expected location.
     Maybe you accidentally invoked bitbake from the wrong directory?
     DEBUG: Removed the following variables from the environment:
     GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
     GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
     XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
     MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
     GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
     XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
     _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
     UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS

Основная часть вывода относится к переменным окружения, не связанным напрямую с BitBake. Однако первая фраза о переменной BBPATH и файле conf/bblayers.conf важна для понимания. При запуске BitBake выполняется поиск метаданных и переменная BBPATH говорит, где нужно их искать. Без этой переменной Bitbake не может найти конфигурационных файлов (.conf) и заданий (.bb), а также файла bitbake.conf.

Настройка BBPATH. В этом примере переменную BBPATH можно задать как выше было показано для PATH,но более эффективным способом является ее установка в конфигурационном файле для каждого проекта.
```
$ BBPATH="projectdirectory" $ export BBPATH
```
В первой команде следует указать реальный каталог проекта и BitBake будет искать в нем метаданные. При указании проекта недопустимо использовать символ ~, поскольку BitBake не преобразует его.

Запуск Bitbake.

     $ bitbake
     ERROR: Traceback (most recent call last):
       File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
         return func(fn, *args)
       File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
         return bb.parse.handle(fn, data, include)
       File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
         return h['handle'](fn, data, include)
       File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
         abs_fn = resolve_file(fn, data)
       File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
         raise IOError("file %s not found in %s" % (fn, bbpath))
     IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello

     ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello

Из вывода видно, что BitBake не может найти в каталоге проекта файл conf/bitbake.conf, без которого не может работать.

Создание файла conf/bitbake.conf. Этот файл содержит многочисленные переменные, используемые BitBake для файлов метаданных и заданий. В нашем примере нужно создать файл в каталоге проекта и задать в нем некоторые важные переменные BitBake. Пример файла доступен по ссылке http://git.openembedded.org/bitbake/tree/conf/bitbake.conf.
```
     $ mkdir conf
```
Далее следует с помощью подходящего редактора создать в новом каталоге файл bitbake.conf.
```
     PN  = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"

     TMPDIR  = "${TOPDIR}/tmp"
     CACHE   = "${TMPDIR}/cache"
     STAMP   = "${TMPDIR}/${PN}/stamps"
     T       = "${TMPDIR}/${PN}/work"
     B       = "${TMPDIR}/${PN}"
```
Без переменной PN, переменные STAMP, TиBне позволят работать более чем одному заданию. Можно установить вPN значение, похожее на используемое OE и BitBake в принятом по умолчанию файле bitbake.conf,как показано выше, или обновлять вручную каждое задание, устанавливаяPN. Может также потребоваться включение PN в определения переменных STAMP, TиB в файле local.conf.

Переменная TMPDIR указывает каталог, который BitBake использует для вывода сборки и промежуточных файлов, не являющихся кэшируемыми данными для процесса Setscene. Каталог временных файлов можно без опаски удалять перед повторной сборкой и сборочный процесс BitBake создаст его заново.

Запуск Bitbake. После создания файла conf/bitbake.conf можно снова ввести команду bitbake.

$ bitbake
ERROR: Traceback (most recent call last):
  File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
    return func(fn, *args)
  File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
    bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
  File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
    include(fn, file, lineno, d, "inherit")
  File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
    raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
    ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass

ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass

Сейчас BitBake не может найти файл classes/base.bbclass и нужно создать его.

Создание classes/base.bbclass. BitBake использует файлы классов для хранения общего кода и функций. Для работы нужно иметь, как минимум, файл classes/base.bbclass. Класс base неявно наследуется каждым заданием. BitBake ищет класс в каталоге classes внутри проекта (hello/classes в этом примере).
```
     $ cd $HOME/hello
     $ mkdir classes 
```
В новом каталоге нужно создать класс base.bbclass с единственной строкой addtask build. Минимальной задачей при запуске BitBake является выполнение do_buildи в нашем примере ничего другого не требуется.
Запуск Bitbake. После создания файла classes/base.bbclass можно снова ввести команду bitbake.

$ bitbake
```
Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
```
BitBake больше не выдает сообщений об ошибках, однако говорит о том, что делать при сборке нечего. Нужно подготовить задание, которое BitBake будет выполнять.
Создание уровня. Хотя в нашем элементарном примере можно обойтись без своего уровня, использование уровня в каждом проекте является хорошим тоном и позволяет отделить код от метаданных общего пользования, применяемых BitBake. Назовем наш уровень mylayer. Уровень должен включать, по меньшей мере, файл задания и конфигурации уровня.
```
     $ cd $HOME
     $ mkdir mylayer
     $ cd mylayer
     $ mkdir conf
```
В каталоге conf создаем файл layer.conf, как показано ниже.
```
     BBPATH .= ":${LAYERDIR}"

     BBFILES += "${LAYERDIR}/*.bb"

     BBFILE_COLLECTIONS += "mylayer"
     BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
```
Затем создаем файл задания printhello.bb в каталоге проекта, как показано ниже.
```
     DESCRIPTION = "Prints Hello World"
     PN = 'printhello'
     PV = '1'

     python do_build() {
        bb.plain("********************");
        bb.plain("*                  *");
        bb.plain("*  Hello, World!   *");
        bb.plain("*                  *");
        bb.plain("********************");
     }
```
Файл содержит описание, имя и версию задания, а также задачу do_build, которая выводит сообщение «Hello World» на консоль.
Запуск Bitbake с указанием цели. Цель сборки BitBake и можно ввести команду для сборки.
```
     $ cd $HOME/hello
     $ bitbake printhello
     ERROR: no recipe files to build, check your BBPATH and BBFILES?

     Summary: There was 1 ERROR message shown, returning a non-zero exit code.
```
Сообщение об ошибке говорит, что BitBake не может найти задание, поскольку нет файла conf/bblayers.conf со списком уровней проекта.
Создание файла conf/bblayers.conf, указывающего уровни проекта. Файл должен размещаться в каталоге conf внутри проекта (hello/conf в нашем примере). Содержимое файла для нашего примера приведено ниже.
```
     BBLAYERS ?= " \
       /home/<you>/mylayer \
       "
```

Запуск Bitbake с указанием цели. Файл конфигурации bblayers.conf создан и можно повторить команду.

     $ bitbake printhello
     Parsing recipes: 100% |##################################################################################|
     Time: 00:00:00
     Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
     NOTE: Resolving any missing task queue dependencies
     NOTE: Preparing RunQueue
     NOTE: Executing RunQueue Tasks
     ********************
     *                  *
     *  Hello, World!   *
     *                  *
     ********************
     NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.

При повторном вводе команды bitbake printhello на консоли не появится приведенного выше текста, поскольку программа BitBake уже выполнила задачу do_build дляprinthello.bbи не будет ее повторять. Если удалить каталог tmp с помощью команды bitbake -c clean printhello и повторить сборку, текст будет выведен снова.

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Source control systems — система управления исходными файлами.

2Board Support Package — пакет поддержки плат.

3World Wide Web Consortium.

4Completely Fair Queuing — беспристрастное управление очередями.

Рубрика: Linux | Комментарии отключены

RFC 8668 Advertising Layer 2 Bundle Member Link Attributes in IS-IS

Опубликовано 01.12.2019 автором Nikolai Malykh

Internet Engineering Task Force (IETF)                  L. Ginsberg, Ed.
Request for Comments: 8668                           Cisco Systems, Inc.
Category: Standards Track                                    A. Bashandy
ISSN: 2070-1721                                             Unaffiliated
                                                             C. Filsfils
                                                     Cisco Systems, Inc.
                                                              M. Nanduri
                                                                  Oracle
                                                                E. Aries
                                                             Arrcus Inc.
                                                           December 2019

Advertising Layer 2 Bundle Member Link Attributes in IS-IS

Анонсирование атрибутов L2 для групповых каналов в IS-IS

PDF

Аннотация

Существуют системы, где интерфейс L3, на котором работает IS-IS, работает как связка (bundle) интерфейсов L2. Существующие анонсы IS-IS поддерживают анонсирование атрибутов канала лишь для интерфейсов L3. Для внешних по отношению к IS-IS элементов, желающих управлять отдельными физическими каналами, входящими в группу (bundle) интерфейсов L2, нужны сведения об атрибутах членов группы.

Этот документ добавляет в IS-IS возможность анонсирования атрибутов канала L2 членов группы.

Статус документа

Документ относится к категории Internet Standards Track.

Документ является результатом работы IETF¹ и представляет согласованный взгляд сообщества IETF. Документ прошёл открытое обсуждение и был одобрен для публикации IESG². Дополнительную информацию о стандартах Internet можно найти в разделе 2 в RFC 7841.

Информацию о текущем статусе документа, ошибках и способах обратной связи можно найти по ссылке https://www.rfc-editor.org/info/rfc8668.

Авторские права

К документу применимы права и ограничения, указанные в BCP 78 и IETF Trust Legal Provisions и относящиеся к документам IETF (http://trustee.ietf.org/license-info), на момент публикации данного документа. Прочтите упомянутые документы внимательно. Фрагменты программного кода, включённые в этот документ, распространяются в соответствии с упрощённой лицензией BSD, как указано в параграфе 4.e документа IETF Trust Legal Provisions, без каких-либо гарантий (как указано в Simplified BSD License).

1. Введение

Существуют системы, где интерфейс L3, на котором работает IS-IS, работает как связка интерфейсов L2, например, группа агрегирования каналов (Link Aggregation Group или LAG) [IEEE802.1AX]. Это сокращает число отношений смежности, требуемых для поддержки протокола маршрутизации, при наличии между соседями параллельных каналов. Внешние по отношению к IS-IS элементы, такие как элементы расчёта пути (Path Computation Element или PCE) [RFC4655], могут захотеть управлять потоками на отдельных каналах базовой группы L2. Для этого нужны сведения об атрибутах отдельных каналов группы. Заданное в этом документе расширение протокола обеспечивает средства для анонсирования таких сведений.

Этот документ определяет TLV для анонсирования сведений об атрибутах каждого канала L2, входящего в интерфейс L3, на котором работает протокол IS-IS.

В [RFC8667] добавлен новый атрибут канала — идентификатор сегмента смежности (adjacency segment identifier или Adj-SID), который можно использовать как инструкцию для пересылки трафика через конкретный канал. Этот документ добавляет TLV для анонсирования Adj-SID каналов группы L2.

Отметим, что заданные в этом документе новые анонсы предназначения для внешних (по отношению к IS-IS) элементов. Указанные ниже элементы не определены и/или выходят за рамки этого документа.

Анонсируемые атрибуты канала (определяются потребностями внешних элементов).
Минимальный или принятый по умолчанию набор атрибутов канала.
Способ настройки этих атрибутов.
Способы использования анонсов.
Возможное влияние использования анонсов на поток трафика в сети.
Способы передачи анонсов внешним элементам.

2. Уровни требований

Ключевые слова должно (MUST), недопустимо (MUST NOT), требуется (REQUIRED), нужно (SHALL), не следует (SHALL NOT), следует (SHOULD), не нужно (SHOULD NOT), рекомендуется (RECOMMENDED), не рекомендуется (NOT RECOMMENDED), возможно (MAY), необязательно (OPTIONAL) в данном документе интерпретируются в соответствии с BCP 14 [RFC2119] [RFC8174] тогда и только тогда, когда они выделены шрифтом, как показано здесь.

3. L2 Bundle Member Attributes TLV

Добавляется TLV для анонсирования атрибутов L2 Bundle Member. Хотя большая часть информации идентична применяемой в анонсах Extended IS Neighbor и используются те же суб-TLV (22 и 222), применяется новый TLV, чтобы изменения в анонсах атрибутов канала L2 Bundle Member не вызывали ненужных действия процесса решения (Decision Process) [ISO10589].

Анонсирование этих сведений предполагает, что указанный канал входит в группу L2 Bundle, связанную с указанным Parent L3 Neighbor, и канал находится в рабочем состоянии. Поэтому анонсы должны отзываться, если канал перестаёт работать (down) или исключается из указанной группы L2 Bundle.

Для нового TLV используется пространство суб-TLV, заданное для TLV 22, 23, 141, 222, 223.

Формат TLV описан ниже.

L2 Bundle Member Attributes

Type

Length

Число последующих октетов.

Parent L3 Neighbor Descriptor

L3 Neighbor System ID + pseudonode ID (7 октетов)

Flags

1-октетное поле флагов, описанное ниже.

 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|P|             |
+-+-+-+-+-+-+-+-+

P-Flag

Если этот флаг установлен (1), за полем флагов слаху же размещается один или несколько суб-TLV, описанных в параграфе 3.1. При сброшенном флаге такие суб-TLV не присктствуют.

Остальные биты флагов

Должны сбрасываться (0) при отправке и игнорироваться при получении.

Один или несколько дескрипторов L2 Bundle Attribute Descriptor, описанных ниже.

Length of L2 Bundle Attribute Descriptor (1 октет)

Примечание. Учитываются все поля, описанные ниже.

Number of L2 Bundle Member Descriptors (1 октет)

L2 Bundle Member Link Local Identifiers (4 * Number of L2 Bundle Member Descriptors октетов)

Примечание. L2 Bundle Member Descriptor — это Link Local Identifier, как указано в [RFC4202].

Sub-TLV(s)

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

Примечание. В данном TLV присутствует лишь один Parent L3 Neighbor Descriptor. В одном TLV может указываться несколько L2 Bundle Attribute Descriptor.

3.1. Параллельные смежности L3

При наличии нескольких отношений смежности L3 с одним соседо нужна дополнительная информация для однозначного указания L3 Neighbor. Для этого применяется 1 (и только 1) из приведённых ниже суб-TLV:

IPv4 Interface Address (sub-TLV 6 из [RFC5305]);
IPv6 Interface Address (sub-TLV 12 из [RFC6119]);
Link Local/Remote Identifiers (sub-TLV 4 из [RFC5307]).

При установленном бите P-Flag в поле флагов Parent L3 Neighbor Descriptor должен присутствовать 1 (и только 0) из указанных выше суб-TLV. Выбранный суб-TLV должен следовать сразу после флагов, как указано в параграфе 3.

Эти суб-TLV можно не указывать, если с соседом нет параллельных отношений смежности.

3.2. Суб-TLV для общих атрибутов

Эти суб-TLV анонсируют одну копию атрибута (например, полосу канала). Атрибут применяется ко всем членам L2 Bundle Members в наборе, указанном предыдущим L2 Bundle Member Attribute Descriptor. В наборе суб-TLV под предшествующим L2 Bundle Member Attribute Descriptor может присутствовать не долее одной копии данного суб-TLV в этой категории. При наличии нескольких копий данного суб-TLV все копии должны игнорироваться.

Набор L2 Bundle Member Descriptor, которые могут анонсироваться под одним L2 Bundle Member Attribute Descriptor, ограничен числом членов группы (bundle), использующих набор атрибутов, анонсируемых в суб-TLV общих атрибутов.

Все имеющиеся суб-TLV, указанные в реестре IANA для суб-TLV в TLV 22, 23, 141, 222, 223, относятся к суб-TLV общих атрибутов, если в этом документе не указано иное.

4. Анонсирование L2 Bundle Member Adj-SID

В [RFC8667] заданы суб-TLV для анонсирования смежности L3 — Adj-SID. Однако в них поддерживается анонсирование лишь одного Adj-SID. Поскольку ожидается, что во многих внедренийх каждый L2 Bundle Member будет иметь уникальные Adj-SID, желательно определить новый суб-TLV для более эффективного кодирования набора Adj-SID в одном суб-TLV. Добавлены два новых суб-TLV для поддержки анонсирования Adj-SID членов L2 Bundle. Формат этих суб-TLV похож на используемый для смежности L3, но оптимизирован для включения набора Adj-SID (по одному на L2 Bundle Member) в один суб-TLV.

Два новых -TLV, определённых в последующих параграфах, не относятся к суб-TLV общих атрибутов.

4.1. Суб-TLV L2 Bundle Member Adjacency Segment Identifier

Этот суб-TLV служит для анонсирования Adj-SID членов L2 Bundle, связанных с родительскими отношениями смежности L3 (point-to-point). Формат суб-TLV показан ниже.

Type

41 (1 октет)

Length

Переменное значение (1 октет)

Flags

1-октетное поле флагов, описанных ниже.

 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|F|*|V|L|S|P|   |
+-+-+-+-+-+-+-+-+

F-Flag

Флаг семейства адресов (Address-Family). Сброшенный (0) флаг Adj-SID указывает L2 Bundle Member с исходящей инкапсуляцией IPv4, установленный — с IPv6.

V-Flag

Флаг значения (Value), устанавливаемый, когда Adj-SID содержит значение. По умолчанию флаг установлен.

L-Flag

Флаг локальности (Local), устанавливаемый, когда Adj-SID имеет локальную значимость. По умолчанию флаг установлен.

S-Flag

Флаг набора (Set), установка которого показывает, что Adj-SID относится к группе членов L2 Bundle (и может назначаться также другим членам L2 Bundle).

P-Flag

Флаг постоянства (Persistent), установка которого указывает постоянное выделение Adj-SID, т. е. значение сохраняется при перезапуске маршрутизатора и/или отключении-включении интерфейса.

Остальные биты

Должны сбрасываться (0) при передаче и игнорироваться при получении.

Примечание. Флаги намеренно сделаны совпадающими с флагами L3 ADJ-SID из [RFC8667]. * указывает флаг, используемый в L3 Adj-SID суб-TLV, но не применяемый в этом суб-TLV. Его следует сбрасывать при передаче, а при получении флаг должен игнорироваться.

Weight

1-октетное значение, представляющее вес Adj-SID для распределения нагрузки. Использование веса описано в [RFC8402].

Примечание. Флаги и вес являются общими для всех членов L2 Bundle, указанных в L2 Bundle Attribute Descriptor.

L2 Bundle Member Adj-SID Descriptors

Должен указываться один дескриптор для каждого члена L2 Bundle, анонсируемого под предшествующим L2 Bundle Member Attribute Descriptor. Каждый дескриптор содержит одно из указанных ниже полей.

SID/Index/Label

В соответствии с флагами V и L это поле содержит одно из указанных ниже значений.

3-октетная локальная метка, где 20 битов справа служат для представления значения. Флаги V и L в этом случае должны быть установлены (1).
4-октетный индекс, указывающий смещение в пространстве SID/Label, анонсированном этим маршрутизатором (см. [RFC8667]). Флаги V и L в этом случае должны быть сброшены (0).

4.2. Суб-TLV L2 Bundle Member LAN Adjacency SID

Этот суб-TLV служит для анонсирования Adj-SID членов L2 Bundle, связанных с родительской смежностью L3, которая является смежностью в ЛВС. В подсетях ЛВС выбирается назначенная промежуточная система (Designated Intermediate System или DIS) выбирается, которая создаёт Pseudonode-LSP (PN-LSP) с включением всех соседей DIS. При использовании маршрутизации по сегмента (Segment Routing) каждый маршрутизатор в ЛВС может анонсировать Adj-SID каждого из своих соседей по ЛВС. Для каждого члена L2 Bundle маршрутизатор может анонсировать Adj-SID каждому соседу по ЛВС. Формат суб-TLV показан ниже.

Type

42 (1 октет)

Length

Переменное значение (1 октет)

Neighbor System ID

6 octets

Flags

1-октетное поле флагов, описанных ниже.

 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|F|*|V|L|S|P|   |
+-+-+-+-+-+-+-+-+

F-Flag

V-Flag

Флаг значения (Value), устанавливаемый, когда Adj-SID содержит значение. По умолчанию флаг установлен.

L-Flag

S-Flag

P-Flag

Остальные биты

Должны сбрасываться (0) при передаче и игнорироваться при получении.

Weight

1-октетное значение, представляющее вес Adj-SID для распределения нагрузки. Использование веса описано в [RFC8402].

Примечание. Флаги и вес являются общими для всех членов L2 Bundle, указанных в L2 Bundle Attribute Descriptor.

L2 Bundle Member LAN Adjacency SID Descriptors:

SID/Index/Label

В соответствии с флагами V и L это поле содержит одно из указанных ниже значений.

3-октетная локальная метка, где 20 битов справа служат для представления значения. Флаги V и L в этом случае должны быть установлены (1).
4-октетный индекс, указывающий смещение в пространстве SID/Label, анонсированном этим маршрутизатором (см. [RFC8667]). Флаги V и L в этом случае должны быть сброшены (0).

5. Взаимодействие с IANA

Этот документ добавляет показанный ниже TLV в реестр IS-IS TLV Codepoints.

Value

Name

L2 Bundle Member Attributes — атрибуты элемента L2 Bundle

Имя реестра IANA для суб-TLV в TLV 22, 23, 141, 222, 223 было изменено для включения суб-TLV 25. Кроме того, в реестр добавлена колонка, указывающая, какие суб-TLV могут присутствовать в новом L2 Bundle Member Attributes TLV. Колонка для TLV 25 включает одно из указанных ниже значений.

Суб-TLV может присутствовать в TLV 25, но недопустимо его совместное использование несколькими членами L2 Bundle.

y(s)

Суб-TLV может присутствовать в TLV 25 и может совместно использоваться несколькими членами L2 Bundle.

Суб-TLV недопустимо включать в TLV 25.

В таблице 1 указаны допустимые установки для всех определённых к настоящему моменту суб-TLV применительно к их использованию в новом L2 Bundle Member Attributes TLV.

Таблица .

Значение	Описание	TLV 25
3	Administrative group (color)	y(s)
4	Link Local/Remote Identifiers	y(s)
6	IPv4 interface address	y(s)
8	IPv4 neighbor address	y(s)
9	Maximum link bandwidth	y(s)
10	Maximum reservable link bandwidth	y(s)
11	Unreserved bandwidth	y(s)
12	IPv6 Interface Address	y(s)
13	IPv6 Neighbor Address	y(s)
14	Extended Administrative Group	y(s)
18	TE Default metric	y(s)
19	Link-attributes	y(s)
20	Link Protection Type	y(s)
21	Interface Switching Capability Descriptor	y(s)
22	Bandwidth Constraints	y(s)
23	Unconstrained TE LSP Count (sub-)TLV	y(s)
24	remote AS number	n
25	IPv4 remote ASBR Identifier	n
26	IPv6 remote ASBR Identifier	n
27	Interface Adjustment Capability Descriptor (IACD)	y(s)
28	MTU	n
29	SPB-Metric	y(s)
30	SPB-A-OALG	y(s)
33	Unidirectional Link Delay	y
34	Min/Max Unidirectional Link Delay	y
35	Unidirectional Delay Variation	y
36	Unidirectional Link Loss	y
37	Unidirectional Residual Bandwidth	y
38	Unidirectional Available Bandwidth	y
39	Unidirectional Utilized Bandwidth	y
40	RTM Capability	n

Этот документ добавляет указанные в таблице 2 суб-TLV в упомянутый выше реестр.

Таблица .

Тип	Описание	22	23	25	141	222	223
41	L2 Bundle Member Adj-SID	n	n	y	n	n	n
42	L2 Bundle Member LAN Adj-SID	n	n	y	n	n	n

6. Вопросы безопасности

Протокол IS-IS уже много лет поддерживает анонсирование сведений об атрибутах каналов, включая их идентификаторы. Анонсы, определённые в этом документе, идентичны анонсам из [RFC4202], [RFC5305], [RFC8570], [RFC8667], но связаны с каналами L2, являющимися частью группового (bundle), на котором работает протокол IS-IS. Поэтому представленные в документе расширения не создают новых проблем безопасности.

Как всегда, при использовании протокола в среде, где возможен несанкционированный доступ к физическим каналам, по которым передаются блоки данных протокола IS-IS (Protocol Data Unit или PDU), возможна организация атак. Рекомендуется использовать проверки подлинности, заданную в [RFC5304] и [RFC5310], для предотвращения таких атак.

7. Литература

7.1. Нормативные документы

[IEEE802.1AX] IEEE, «IEEE Standard for Local and metropolitan area networks — Link Aggregation», IEEE 802.1AX, <https://ieeexplore.ieee.org/document/7055197>.

[ISO10589] International Organization for Standardization, «Information technology — Telecommunications and information exchange between systems — Intermediate System to Intermediate System intra-domain routeing information exchange protocol for use in conjunction with the protocol for providing the connectionless-mode network service (ISO 8473)», ISO/IEC 10589:2002, Second Edition, November 2002.

[RFC2119] Bradner, S., «Key words for use in RFCs to Indicate Requirement Levels», BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC4202] Kompella, K., Ed. and Y. Rekhter, Ed., «Routing Extensions in Support of Generalized Multi-Protocol Label Switching (GMPLS)», RFC 4202, DOI 10.17487/RFC4202, October 2005, <https://www.rfc-editor.org/info/rfc4202>.

[RFC5304] Li, T. and R. Atkinson, «IS-IS Cryptographic Authentication», RFC 5304, DOI 10.17487/RFC5304, October 2008, <https://www.rfc-editor.org/info/rfc5304>.

[RFC5305] Li, T. and H. Smit, «IS-IS Extensions for Traffic Engineering», RFC 5305, DOI 10.17487/RFC5305, October 2008, <https://www.rfc-editor.org/info/rfc5305>.

[RFC5307] Kompella, K., Ed. and Y. Rekhter, Ed., «IS-IS Extensions in Support of Generalized Multi-Protocol Label Switching (GMPLS)», RFC 5307, DOI 10.17487/RFC5307, October 2008, <https://www.rfc-editor.org/info/rfc5307>.

[RFC5310] Bhatia, M., Manral, V., Li, T., Atkinson, R., White, R., and M. Fanto, «IS-IS Generic Cryptographic Authentication», RFC 5310, DOI 10.17487/RFC5310, February 2009, <https://www.rfc-editor.org/info/rfc5310>.

[RFC6119] Harrison, J., Berger, J., and M. Bartlett, «IPv6 Traffic Engineering in IS-IS», RFC 6119, DOI 10.17487/RFC6119, February 2011, <https://www.rfc-editor.org/info/rfc6119>.

[RFC8174] Leiba, B., «Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words», BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8570] Ginsberg, L., Ed., Previdi, S., Ed., Giacalone, S., Ward, D., Drake, J., and Q. Wu, «IS-IS Traffic Engineering (TE) Metric Extensions», RFC 8570, DOI 10.17487/RFC8570, March 2019, <https://www.rfc-editor.org/info/rfc8570>.

[RFC8667] Previdi, S., Ed., Ginsburg, L., Ed., Filsfils, C., Bashandy, A., Gredler, H., and B. Decraene, «IS-IS Extensions for Segment Routing», RFC 8667, DOI 10.17487/RFC8667, December 2019, <https://www.rfc-editor.org/info/rfc8667>.

7.2. Дополнительная литература

[RFC4655] Farrel, A., Vasseur, JP., and J. Ash, «A Path Computation Element (PCE)-Based Architecture», RFC 4655, DOI 10.17487/RFC4655, August 2006, <https://www.rfc-editor.org/info/rfc4655>.

[RFC8402] Filsfils, C., Ed., Previdi, S., Ed., Ginsberg, L., Decraene, B., Litkowski, S., and R. Shakir, «Segment Routing Architecture», RFC 8402, DOI 10.17487/RFC8402, July 2018, <https://www.rfc-editor.org/info/rfc8402>.

Приложение A. Примеры кодирования

Ниже представлен пример кодирования анонсов L2 Bundle для случая двух параллельных отношений смежности с соседом, имеющим system-id = 1234.1234.1234.00. Две связки каналов L2 имеют показанные ниже наборы атрибутов.

   L3 Adjacency #1
   L3 IPv4 local link address: 192.0.2.1

Четыре члена связки каналов имеют показанные в таблице 3 атрибуты.

Таблица .

Номер	Link Local ID	Полоса	Adj-SID/Weight
1	0x11111111	1G	0x11111/1
2	0x11112222	1G	0x11112/1
3	0x11113333	10G	0x11113/1
4	0x11114444	10G	0x11114/1

   L3 Adjacency #2
   L3 IPv4 local link address: 192.0.2.2

Три члена связки каналов имеют показанные в таблице 4 атрибуты.

Таблица .

Номер	Link Local ID	Полоса	Adj-SID/Weight
1	0x22221111	10G	22221/1
2	0x22222222	10G	22222/1
3	0x22223333	10G	22223/1

Для этого случая требуется пара TLV, по одному для каждой смежности L3.

TLV для Adjacency #1

    0                   1
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(25)     | Length(64)    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parent L3 Neighbor Descriptor

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Neighbor System-ID octets 1-4: 1234.1234                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | System-ID octets 5-6: 1234    | P-node: 00    |1|0|0|0|0|0|0|0|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

IPv4 Interface Address Sub-TLV

    0                   1
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(6)      | Length(4)     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | IPv4 address: 192.0.2.1                                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

L2 Bundle Attribute Descriptors

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Len:9+6+10 = 25| # Desc: 2     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Link Local Identifier Bundle Member #1: 0x11111111            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Link Local Identifier Bundle Member #2: 0x11112222            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Maximum Link Bandwidth Sub-TLV

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(9)       | Length(4)    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Bandwidth Value: 1G/8                                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

L2 Bundle Member Adj-SID Sub-TLV

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(41)     | Length(8)     |0|0|1|1|0|0|0|0| Weight: 1     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Local Label Bundle Member #1: 0x11111         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Local Label Bundle Member #2: 0x11112         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

L2 Bundle Attribute Descriptors

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Len:9+6+10 = 25| # Desc: 2     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Link Local Identifier Bundle Member #3: 0x11113333            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Link Local Identifier Bundle Member #4: 0x11114444            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Maximum Link Bandwidth Sub-TLV

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(9)       | Length(4)    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Bandwidth Value: 10G/8                                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

L2 Bundle Member Adj-SID Sub-TLV

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(41)     | Length(8)     |0|0|1|1|0|0|0|0| Weight: 1     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Local Label Bundle Member #3: 0x11113         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Local Label Bundle Member #4: 0x11114         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

TLV for Adjacency #2:

    0                   1
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(25)     | Length(46)    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parent L3 Neighbor Descriptor

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Neighbor System-ID octets 1-4: 1234.1234                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | System-ID octets 5-6: 1234    | P-node: 00    |1|0|0|0|0|0|0|0|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

IPv4 Interface Address Sub-TLV

    0                   1
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(6)      | Length(4)     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | IPv4 address: 192.0.2.2                                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

L2 Bundle Attribute Descriptors

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Len:13+6+13=32 | # Desc: 3     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Link Local Identifier Bundle Member #1: 0x22221111            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Link Local Identifier Bundle Member #2: 0x22222222            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Link Local Identifier Bundle Member #3: 0x22223333            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Maximum Link Bandwidth Sub-TLV

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(9)       | Length(4)    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Bandwidth Value: 10G/8                                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

L2 Bundle Member Adj-SID Sub-TLV

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Type(41)     | Length(11)    |0|0|1|1|0|0|0|0| Weight: 1     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Local Label Bundle Member #1: 0x22221         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Local Label Bundle Member #2: 0x22222         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Local Label Bundle Member #3: 0x22223         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Благодарности

Авторы благодарны Jon Mitchell за внимательное рецензирование.

Участник работы

Ниже указан человек, который внёс существенный вклад в этот документ и должен считаться соавтором.

Stefano Previdi

Huawei Technologies

Italy

Email: stefano@previdi.net

Адреса авторов

Les Ginsberg (editor)

Cisco Systems, Inc.

Email: ginsberg@cisco.com

Ahmed Bashandy

Unaffiliated

United States of America

Email: abashandy.ietf@gmail.com

Clarence Filsfils

Cisco Systems, Inc.

Email: cf@cisco.com

Mohan Nanduri

Oracle

Email: mohan.nanduri@oracle.com

Ebben Aries

Arrcus Inc.

2077 Gateway Place, Suite #400

San Jose, CA 95119

United States of America

Email: exa@arrcus.com

Перевод на русский язык

nmalykh@protokols.ru

1Internet Engineering Task Force — комиссия по решению инженерных задач Internet.

2Internet Engineering Steering Group — комиссия по инженерным разработкам Internet.

Рубрика: RFC | Оставить комментарий

RFC 8675 A YANG Data Model for Tunnel Interface Types

Опубликовано 20.11.2019 автором Nikolai Malykh

Internet Engineering Task Force (IETF)                      M. Boucadair
Request for Comments: 8675                                        Orange
Category: Standards Track                                      I. Farrer
ISSN: 2070-1721                                      Deutsche Telekom AG
                                                                R. Asati
                                                     Cisco Systems, Inc.
                                                           November 2019

A YANG Data Model for Tunnel Interface Types

Модель данных YANG для типов туннельных интерфейсов

PDF

Аннотация

Этот документ задаёт первую версию модуля YANG iana-tunnel-type, включающую набор поддерживаемых IANA идентификаторов YANG, служащих для указания типов туннельных интерфейсов. Модуль отражает реестр tunnelType, поддерживаемый IANA. Последнюю версию этого модуля YANG можно найти на web-сайте IANA.

Значения типов туннелей не добавляются напрямую в модуль YANG и должны сначала включаться в реестр tunnelType. После регистрации в IANA новой схемы туннелирования или даже существующей схемы, которая ещё не включена в реестр (например LISP, NSH) агентство IANA будет соответствующим образом обновлять модуль YANG.

Некоторые методы туннелирования, определённые в IETF, не включены в текущий реестр IANA. Целью этого документа не является обновление имеющегося реестра IANA для указания полного списка туннельных технологий. При регистрации нового типа туннеля нужно следовать процедуре IETF для типов интерфейсов.

Статус документа

Документ относится к категории Internet Standards Track.

Информация о текущем статусе документа, найденных ошибках и способах обратной связи доступна по ссылке https://www.rfc-editor.org/info/rfc8675.

Авторские права

1. Введение

Этот документ задаёт исходную версию модуля YANG iana-tunnel-type, содержащую набор поддерживаемых IANA идентификаторов YANG, указывающих типы туннельных интерфейсов. Модель отражает реестр IANA tunnelType в реестре SMI Numbers [TUNNELTYPE-IANA-REGISTRY]. Последняя версия модуля доступна на web-сайте IANA.

В модуль Interface [RFC8343] можно добавить расширения в зависимости от типа туннеля. Пример такого добавления приведён в Приложении A. В задачи документа не входит задание связанных с туннелями расширений для каждой технологии инкапсуляции, они рассматриваются в отдельных документах, например, [RFC8676]. Обновление имеющегося реестра IANA tunnelType [TUNNELTYPE-IANA-REGISTRY] с указанием полного списка туннельных технологий также не является задачей этого документа. Рекомендации и процедуры регистрации для типов и субтипов интерфейсов приведены в [IFTYPE-REG].

Этот документ использует базовые типа YANG, определённые в [RFC6991], и следует архитектуре хранилищ данных управления сетью (Network Management Datastore Architecture или NMDA) [RFC8342].

Терминология для описания модулей YANG определена в [RFC7950], значения символов в диаграммах деревьев — в [RFC8340].

2. Модуль YANG для типов туннелей IANA

Модуль iana-tunnel-type импортирует модуль iana-if-type, заданный в [RFC7224].

Исходная версия этого модуля включает типы туннелей, определённые в [RFC4087], [RFC7856], [RFC7870], [RFC6346].

   <CODE BEGINS> file "iana-tunnel-type@2019-11-16.yang"
   module iana-tunnel-type {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:iana-tunnel-type";
     prefix iana-tunnel-type;

     import iana-if-type {
       prefix ift;
       reference
         "RFC 7224: IANA Interface Type YANG Module";
     }

     organization
       "IANA";
     contact
       "Internet Assigned Numbers Authority

        Postal: ICANN
             12025 Waterfront Drive, Suite 300
             Los Angeles, CA  90094-2536
             United States of America
        Tel:    +1 310 301 5800
        <mailto:iana@iana.org>";
     description
       "Этот модуль содержит набор идентификаторов YANG, заданных 
        IANA и используемых как типы туннельных интерфейсов.

        Авторские права (Copyright (c) 2019) принадлежат IETF Trust и
        лицам, указанным как авторы. Все права защищены.

        Распространение и применение модуля в исходной или двоичной 
        форме с изменениями или без таковых разрешено в соответствии с
        лицензией Simplified BSD License, изложенной в параграфе 4.c
        IETF Trust's Legal Provisions Relating to IETF Documents
        (https://trustee.ietf.org/license-info). 

        Эта версия модуля YANG является частью RFC 8675, где правовые
        аспекты приведены более полно.";

     revision 2019-11-16 {
       description
         "Исходный выпуск.";
       reference
         "RFC 8675: A YANG Data Model for Tunnel Interface Types";
     }

     identity other {
       base ift:tunnel;
       description
         "Ни один из указанных ниже типов.";
       reference
         "RFC 4087: IP Tunnel MIB";
     }

     identity direct {
       base ift:tunnel;
       description
         "Нет промежуточного заголовка.";
       reference
         "RFC 2003: IP Encapsulation within IP
          RFC 4213: Basic Transition Mechanisms for IPv6 Hosts
                    and Routers";
     }

     identity gre {
       base ift:tunnel;
       description
         "Инкапсуляция GRE.";
       reference
         "RFC 1701: Generic Routing Encapsulation (GRE)
          RFC 1702: Generic Routing Encapsulation over IPv4 networks
          RFC 7676: IPv6 Support for Generic Routing Encapsulation
                    (GRE)";
     }

     identity minimal {
       base ift:tunnel;
       description
         "Минимальная инкапсуляция.";
       reference
         "RFC 2004: Minimal Encapsulation within IP";
     }

     identity l2tp {
       base ift:tunnel;
       description
         "Инкапсуляция L2TP.";
       reference
         "RFC 2661: Layer Two Tunneling Protocol 'L2TP'";
     }

     identity pptp {
       base ift:tunnel;
       description
         "Инкапсуляция PPTP.";
       reference
         "RFC 2637: Point-to-Point Tunneling Protocol (PPTP)";
     }

     identity l2f {
       base ift:tunnel;
       description
         "Инкапсуляция L2F.";
       reference
         "RFC 2341: Cisco Layer Two Forwarding (Protocol) 'L2F'";
     }

     identity udp {
       base ift:tunnel;
       description
         "Инкапсуляция UDP.";
       reference
         "RFC 1234: Tunneling IPX Traffic through IP Networks,
          RFC 8085: UDP Usage Guidelines, Section 3.1.11";
     }

     identity atmp {
       base ift:tunnel;
       description
         "Инкапсуляция ATMP.";
       reference
         "RFC 2107: Ascend Tunnel Management Protocol - ATMP";
     }

     identity msdp {
       base ift:tunnel;
       description
         "Инкапсуляция MSDP.";
       reference
         "RFC 3618: Multicast Source Discovery Protocol (MSDP)";
     }

     identity sixtofour {
       base ift:tunnel;
       description
         "Инкапсуляция 6to4.";
       reference
         "RFC 3056: Connection of IPv6 Domains via IPv4 Clouds";
     }

     identity sixoverfour {
       base ift:tunnel;
       description
         "Инкапсуляция 6over4.";
       reference
         "RFC 2529: Transmission of IPv6 over IPv4 Domains without
                    Explicit Tunnels";
     }

     identity isatap {
       base ift:tunnel;
       description
         "Инкапсуляция ISATAP.";
       reference
         "RFC 5214:  Intra-Site Automatic Tunnel Addressing Protocol
                    (ISATAP)";
     }

     identity teredo {
       base ift:tunnel;
       description
         "Инкапсуляция Teredo.";
       reference
         "RFC 4380: Teredo: Tunneling IPv6 over UDP through
                    Network Address Translations (NATs)";
     }

     identity iphttps {
       base ift:tunnel;
       description
         "Туннельный протокол IP через HTTPS (IP-HTTPS).";
       reference
         "Microsoft Corporation, IP over HTTPS (IP-HTTPS) Tunneling
          Protocol Specification,
          https://msdn.microsoft.com/en-us/library/dd358571.aspx";
     }

     identity softwiremesh {
       base ift:tunnel;
       description
         "Сеть из мягких проводов (softwire mesh tunnel).";
       reference
         "RFC 5565: Softwire Mesh Framework";
     }

     identity dslite {
       base ift:tunnel;
       description
         "Туннель DS-Lite.";
       reference
         "RFC 6333: Dual-Stack Lite Broadband Deployments Following
                    IPv4 Exhaustion";
     }

     identity aplusp {
       base ift:tunnel;
       description
         "Инкапсуляция A+P.";
       reference
         "RFC 6346: The Address plus Port (A+P) Approach to the IPv4
                    Address Shortage";
     }
   }
   <CODE ENDS>

3. Вопросы безопасности

Заданный этим документом модуль YANG определяет схему для данных, предназначенную для доступа через сеть с использованием протоколов управления, таких как NETCONF [RFC6241] или RESTCONF [RFC8040]. Нижним уровнем NETCONF служит защищённый транспорт с обязательной поддержкой SSH (Secure Shell) [RFC6242]. Нижним уровнем RESTCONF служит протокол HTTPS с обязательной поддержкой защиты на транспортном уровне (TLS) [RFC8446].

Модель контроля доступа к настройкам сети (Network Configuration Access Control Model или NACM) [RFC8341] обеспечивает возможность разрешить доступ лишь определённых пользователей NETCONF или RESTCONF к заранее заданному подмножеству операций NETCONF или RESTCONF и содержимого.

Заданный здесь модуль YANG указывает реестр iana-tunnel-types. Эти идентификаторы предназначены для применения в других модулях YANG и сами по себе не раскрывают каких-либо узлов, доступных для записи, только для чтения или RPC. Поэтому с заданным здесь модулем не связано каких-либо новых вопросов безопасности.

4. Взаимодействие с IANA

4.1. Модуль YANG

Агентство IANA зарегистрировало URI в субреестре ns реестра IETF XML Registry [RFC3688]

   URI:  urn:ietf:params:xml:ns:yang:iana-tunnel-type
   Registrant Contact:  IANA
   XML:  N/A; запрошенный URI является пространством имён XML.

Агентство IANA зарегистрировало модуль YANG в субреестре YANG Module Names [RFC7950] реестра YANG Parameters

   Name:  iana-tunnel-type
   Namespace:  urn:ietf:params:xml:ns:yang:iana-tunnel-type
   Prefix:  iana-tunnel-type
   Reference:  RFC 8675

Документ определяет исходную версию поддерживаемого IANA модуля YANG iana-tunnel-type. Агентство IANA добавило в реестр примечание:

Значения типов туннелей недопустимо напрямую добавлять в модуль YANG iana-tunnel-type. Они должны добавляться в субреестр tunnelType (внутри реестра ifType definitions) [IANA registry smi-numbers].

При добавлении нового типа туннеля в субреестр tunnelType в модуль YANG iana-tunnel-type должен добавляться оператор identity. Имя identity является приведённым к нижнему регистру вариантом соответствующего перечисляемого значения из IANAifType-MIB (т. е. IANAtunnelType). В оператор identity следует включать указанные ниже субоператоры.

base

ift:tunnel.

description

Копия описания из реестра.

reference

Копия ссылки из реестра с указанием названия документа.

Невыделенные и резервные значения не включаются в модуль.

При обновлении модуля YANG iana-tunnel-type в него должен добавляться новый оператор revision перед имеющимися одноименными операторами.

Агентство IANA добавило в реестр tunnelType примечание:

При обновлении реестра должен обновляться модуль YANG iana-tunnel-type, как указано в RFC 8675.

4.2. Обновления таблицы IANA tunnelType

Агентство IANA обновило показанные в таблице 1 записи субреестра tunnelType внутри реестра SMI Numbers [TUNNELTYPE-IANA-REGISTRY], в соответствии с таблицей 2.

Таблица 1. Старая таблица.

Десятичное значение	Имя	Описание	Документ
2	direct	Нет промежуточного заголовка	[RFC4087]
3	gre	Инкапсуляция GRE	[RFC4087]
4	minimal	Минимальная инкапсуляция	[RFC4087]
5	l2tp	Инкапсуляция L2TP	[RFC4087]
6	pptp	Инкапсуляция PPTP	[RFC4087]
7	l2f	Инкапсуляция L2F	[RFC4087]
8	udp	Инкапсуляция UDP	[RFC4087]
9	atmp	Инкапсуляция ATMP	[RFC4087]
10	msdp	Инкапсуляция MSDP	[RFC4087]
11	sixToFour	Инкапсуляция 6to4	[RFC4087]
12	sixOverFour	Инкапсуляция 6over4	[RFC4087]
13	isatap	Инкапсуляция ISATAP	[RFC4087]
14	teredo	Инкапсуляция Teredo	[RFC4087]
16	softwireMesh	Туннель softwire mesh	[RFC7856]
17	dsLite	Туннель DS-Lite	[RFC7870]

Таблица 2. Новая таблица.

Десятичное значение	Имя	Описание	Документ
2	direct	Нет промежуточного заголовка	[RFC2003][RFC4213]
3	gre	Инкапсуляция GRE	[RFC1701][RFC1702][RFC7676]
4	minimal	Минимальная инкапсуляция	[RFC2004]
5	l2tp	Инкапсуляция L2TP	[RFC2661]
6	pptp	Инкапсуляция PPTP	[RFC2637]
7	l2f	Инкапсуляция L2F	[RFC2341]
8	udp	Инкапсуляция UDP	[RFC8085]
9	atmp	Инкапсуляция ATMP	[RFC2107]
10	msdp	Инкапсуляция MSDP	[RFC3618]
11	sixToFour	Инкапсуляция 6to4	[RFC3056]
12	sixOverFour	Инкапсуляция 6over4	[RFC2529]
13	isatap	Инкапсуляция ISATAP	[RFC5214]
14	teredo	Инкапсуляция Teredo	[RFC4380]
16	softwireMesh	Туннель softwire mesh	[RFC5565]
17	dsLite	Туннель DS-Lite	[RFC6333]

5. Литература

5.1. Нормативные документы

[RFC3688] Mealling, M., «The IETF XML Registry», BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.

[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., «Network Configuration Protocol (NETCONF)», RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.

[RFC6242] Wasserman, M., «Using the NETCONF Protocol over Secure Shell (SSH)», RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.

[RFC6991] Schoenwaelder, J., Ed., «Common YANG Data Types», RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/info/rfc6991>.

[RFC7224] Bjorklund, M., «IANA Interface Type YANG Module», RFC 7224, DOI 10.17487/RFC7224, May 2014, <https://www.rfc-editor.org/info/rfc7224>.

[RFC7950] Bjorklund, M., Ed., «The YANG 1.1 Data Modeling Language», RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>.

[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, «RESTCONF Protocol», RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.

[RFC8341] Bierman, A. and M. Bjorklund, «Network Configuration Access Control Model», STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.

[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, «Network Management Datastore Architecture (NMDA)», RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.

[RFC8446] Rescorla, E., «The Transport Layer Security (TLS) Protocol Version 1.3», RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.

[TUNNELTYPE-IANA-REGISTRY] IANA, «Structure of Management Information (SMI) Numbers (MIB Module Registrations)», <https://www.iana.org/assignments/smi-numbers>.

5.2. Дополнительная литература

[IFTYPE-REG] Thaler, D. and D. Romascanu, «Guidelines and Registration Procedures for Interface Types and Tunnel Types», Work in Progress, Internet-Draft, draft-thaler-iftype-reg-06, 2 November 2019, <https://tools.ietf.org/html/draft-thaler-iftype-reg-06>.

[RFC1701] Hanks, S., Li, T., Farinacci, D., and P. Traina, «Generic Routing Encapsulation (GRE)», RFC 1701, DOI 10.17487/RFC1701, October 1994, <https://www.rfc-editor.org/info/rfc1701>.

[RFC1702] Hanks, S., Li, T., Farinacci, D., and P. Traina, «Generic Routing Encapsulation over IPv4 networks», RFC 1702, DOI 10.17487/RFC1702, October 1994, <https://www.rfc-editor.org/info/rfc1702>.

[RFC2003] Perkins, C., «IP Encapsulation within IP», RFC 2003, DOI 10.17487/RFC2003, October 1996, <https://www.rfc-editor.org/info/rfc2003>.

[RFC2004] Perkins, C., «Minimal Encapsulation within IP», RFC 2004, DOI 10.17487/RFC2004, October 1996, <https://www.rfc-editor.org/info/rfc2004>.

[RFC2107] Hamzeh, K., «Ascend Tunnel Management Protocol — ATMP», RFC 2107, DOI 10.17487/RFC2107, February 1997, <https://www.rfc-editor.org/info/rfc2107>.

[RFC2341] Valencia, A., Littlewood, M., and T. Kolar, «Cisco Layer Two Forwarding (Protocol) «L2F»», RFC 2341, DOI 10.17487/RFC2341, May 1998, <https://www.rfc-editor.org/info/rfc2341>.

[RFC2529] Carpenter, B. and C. Jung, «Transmission of IPv6 over IPv4 Domains without Explicit Tunnels», RFC 2529, DOI 10.17487/RFC2529, March 1999, <https://www.rfc-editor.org/info/rfc2529>.

[RFC2637] Hamzeh, K., Pall, G., Verthein, W., Taarud, J., Little, W., and G. Zorn, «Point-to-Point Tunneling Protocol (PPTP)», RFC 2637, DOI 10.17487/RFC2637, July 1999, <https://www.rfc-editor.org/info/rfc2637>.

[RFC2661] Townsley, W., Valencia, A., Rubens, A., Pall, G., Zorn, G., and B. Palter, «Layer Two Tunneling Protocol «L2TP»», RFC 2661, DOI 10.17487/RFC2661, August 1999, <https://www.rfc-editor.org/info/rfc2661>.

[RFC3056] Carpenter, B. and K. Moore, «Connection of IPv6 Domains via IPv4 Clouds», RFC 3056, DOI 10.17487/RFC3056, February 2001, <https://www.rfc-editor.org/info/rfc3056>.

[RFC3618] Fenner, B., Ed. and D. Meyer, Ed., «Multicast Source Discovery Protocol (MSDP)», RFC 3618, DOI 10.17487/RFC3618, October 2003, <https://www.rfc-editor.org/info/rfc3618>.

[RFC4087] Thaler, D., «IP Tunnel MIB», RFC 4087, DOI 10.17487/RFC4087, June 2005, <https://www.rfc-editor.org/info/rfc4087>.

[RFC4213] Nordmark, E. and R. Gilligan, «Basic Transition Mechanisms for IPv6 Hosts and Routers», RFC 4213, DOI 10.17487/RFC4213, October 2005, <https://www.rfc-editor.org/info/rfc4213>.

[RFC4380] Huitema, C., «Teredo: Tunneling IPv6 over UDP through Network Address Translations (NATs)», RFC 4380, DOI 10.17487/RFC4380, February 2006, <https://www.rfc-editor.org/info/rfc4380>.

[RFC5214] Templin, F., Gleeson, T., and D. Thaler, «Intra-Site Automatic Tunnel Addressing Protocol (ISATAP)», RFC 5214, DOI 10.17487/RFC5214, March 2008, <https://www.rfc-editor.org/info/rfc5214>.

[RFC5565] Wu, J., Cui, Y., Metz, C., and E. Rosen, «Softwire Mesh Framework», RFC 5565, DOI 10.17487/RFC5565, June 2009, <https://www.rfc-editor.org/info/rfc5565>.

[RFC6333] Durand, A., Droms, R., Woodyatt, J., and Y. Lee, «Dual-Stack Lite Broadband Deployments Following IPv4 Exhaustion», RFC 6333, DOI 10.17487/RFC6333, August 2011, <https://www.rfc-editor.org/info/rfc6333>.

[RFC6346] Bush, R., Ed., «The Address plus Port (A+P) Approach to the IPv4 Address Shortage», RFC 6346, DOI 10.17487/RFC6346, August 2011, <https://www.rfc-editor.org/info/rfc6346>.

[RFC7676] Pignataro, C., Bonica, R., and S. Krishnan, «IPv6 Support for Generic Routing Encapsulation (GRE)», RFC 7676, DOI 10.17487/RFC7676, October 2015, <https://www.rfc-editor.org/info/rfc7676>.

[RFC7856] Cui, Y., Dong, J., Wu, P., Xu, M., and A. Yla-Jaaski, «Softwire Mesh Management Information Base (MIB)», RFC 7856, DOI 10.17487/RFC7856, May 2016, <https://www.rfc-editor.org/info/rfc7856>.

[RFC7870] Fu, Y., Jiang, S., Dong, J., and Y. Chen, «Dual-Stack Lite (DS-Lite) Management Information Base (MIB) for Address Family Transition Routers (AFTRs)», RFC 7870, DOI 10.17487/RFC7870, June 2016, <https://www.rfc-editor.org/info/rfc7870>.

[RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, «UDP Usage Guidelines», BCP 145, RFC 8085, DOI 10.17487/RFC8085, March 2017, <https://www.rfc-editor.org/info/rfc8085>.

[RFC8340] Bjorklund, M. and L. Berger, Ed., «YANG Tree Diagrams», BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>.

[RFC8343] Bjorklund, M., «A YANG Data Model for Interface Management», RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>.

[RFC8676] Farrer, I., Ed. and M. Boucadair, Ed., «YANG Modules for IPv4-in-IPv6 Address plus Port (A+P) Softwires», RFC 8676, DOI 10.17487/RFC8676, November 2019, <https://www.rfc-editor.org/info/rfc8676>.

Приложение A. Пример использования

Приведённый ниже пример иллюстирует добавление (augment) в модуль YANG Interface связанных с туннелем параметров. В примере добавляется remote-endpoint для туннеля. Дерево модуля имеет вид

   module: example-iftunnel-extension
     augment /if:interfaces/if:interface:
       +--rw remote-endpoint?   inet:ipv6-address

Модуль example-iftunnel-extension импортирует модули из [RFC6991] и [RFC8343] в дополнение к модулю iana-tunnel-type, заданному в этом документе.

   module example-iftunnel-extension {
     yang-version 1.1;

     namespace "urn:ietf:params:xml:ns:yang:example-iftunnel-extension";
     prefix example;

     import ietf-inet-types {
       prefix inet;
       reference
         "RFC 6991: Common YANG Data Types, Section 4";
     }

     import ietf-interfaces {
       prefix if;
       reference
         "RFC 8343: A YANG Data Model for Interface Management";
     }

     import iana-tunnel-type  {
       prefix iana-tunnel-type;
       reference
         "RFC 8675:  A Tunnel Extension to the Interface Management
                     YANG Module";
     }

     organization "IETF Softwire Working Group";

     contact

       "WG Web:   <https://datatracker.ietf.org/wg/softwire/>
        WG List:  <mailto:softwire@ietf.org>

        Author:  Mohamed Boucadair
                 <mailto:mohamed.boucadair@orange.com>";

      description
         "Это пример модуля, расширяющего модуль YANG Interface связанными
          с туннелем параметрами.

          Авторские права (Copyright (c) 2019) принадлежат IETF Trust и
          лицам, указанным как авторы. Все права защищены.

          Распространение и применение модуля в исходной или двоичной 
          форме с изменениями или без таковых разрешено в соответствии с
          лицензией Simplified BSD License, изложенной в параграфе 4.c
          IETF Trust's Legal Provisions Relating to IETF Documents
          (https://trustee.ietf.org/license-info). 

          Эта версия модуля YANG является частью RFC 8675, где правовые
          аспекты приведены более полно.";

     revision 2019-10-21 {
       description
         "Исходный выпуск.";
       reference
         "RFC 8675:  Tunnel Interface Types YANG Module";
     }

     augment "/if:interfaces/if:interface" {
       when "derived-from(if:type, 'iana-tunnel-type:gre')";
       description
         "Дополняет модуль Interface конкретными параметрами туннеля.";

       leaf remote-endpoint {
         type inet:ipv6-address;
         description
           "Адрес IPv6 удалённой точки GRE.";
       }
     }
   }

Благодарности

Большое спасибо Tom Petch и Martin Bjorklund за подробные рецензии и предложения.

Спасибо Andy Bierman за рецензию Yangdoctors.

Спасибо Dale Worley, David Black, Yaron Sheffer за рецензии.

Адреса авторов

Mohamed Boucadair

Orange

35000 Rennes

France

Email: mohamed.boucadair@orange.com

Ian Farrer

Deutsche Telekom AG

CTO-ATI, Landgrabenweg 151

53227 Bonn

Germany

Email: ian.farrer@telekom.de

Rajiv Asati

Cisco Systems, Inc.

7025 Kit Creek Rd.

RTP, NC 27709

United States of America

Email: Rajiva@cisco.com

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Internet Engineering Task Force — комиссия по решению инженерных задач Internet.

2Internet Engineering Steering Group — комиссия по инженерным разработкам Internet.

Рубрика: RFC | Оставить комментарий

RFC 8650 Dynamic Subscription to YANG Events and Datastores over RESTCONF

Опубликовано 14.11.2019 автором Nikolai Malykh

Internet Engineering Task Force (IETF)                           E. Voit
Request for Comments: 8650                                     R. Rahman
Category: Standards Track                              E. Nilsen-Nygaard
ISSN: 2070-1721                                            Cisco Systems
                                                                A. Clemm
                                                               Futurewei
                                                              A. Bierman
                                                               YumaWorks
                                                           November 2019

Dynamic Subscription to YANG Events and Datastores over RESTCONF

Динамическая подписка на события и хранилища YANG по протоколу RESTCONF

PDF

Аннотация

Документ задаёт привязку RESTCONF к свойству динамической подписки для уведомлений по подписке и YANG-Push.

Статус документа

Документ относится к категории Internet Standards Track.

Информацию о текущем статусе документа, ошибках и способах обратной связи можно найти по ссылке https://www.rfc-editor.org/info/rfc8650.

Авторские права

1. Введение

Механизмы для поддержки подписки на события и YANG-Push определены в [RFC8639]. Улучшения [RFC8639], обеспечивающие подписку на хранилища YANG и YANG-Push определены в [RFC8641]. Этот документ задаёт транспортную спецификацию для динамической подписки по протоколу RESTCONF [RFC8040]. Требования к механизмам заимстрованы из [RFC7923].

Потоковые уведомления, инкапсулирующие выталкиваемую информацию, организуются с помощью механизма, заданного в параграфе 6.3 [RFC8040].

2. Терминология

Ключевые слова необходимо (MUST), недопустимо (MUST NOT), требуется (REQUIRED), нужно (SHALL), не следует (SHALL NOT), следует (SHOULD), не нужно (SHOULD NOT), рекомендуется (RECOMMENDED), не рекомендуется (NOT RECOMMENDED), возможно (MAY), необязательно (OPTIONAL) в данном документе интерпретируются в соответствии с BCP 14 [RFC2119] [RFC8174] тогда и только тогда, когда они выделены шрифтом, как показано здесь.

Из [RFC8639] взяты термины dynamic subscription (динамическая подписка), event stream (поток событий), notification message (уведомление), publisher (издатель), receiver (получатель), subscriber (подписчик), subscription (подписка). Термин datastore (хранилище данных) определён в [RFC8342], а поток HTTP/2 сопоставляется с термином stream, определенным в разделе 2 [RFC7540].

3. Динамические подписки

В этом разделе описана организация и поддержика динамических подписок по протоколу RESTCONF [RFC8040]. Подписка на потоки событий в этом случае организуется через вызовы RPC, определённые в параграфе 2.4 [RFC8639], которые передаются через RESTCONF POST. Подписка на хранилища YANG реализуется через дополнения (augment) к [RFC8639], как описано в параграфе 2.4 [RFC8641].

Как описано в параграфе 6.3 [RFC8040], нужно выполнить операцию GET для указанного URI у издателя. Подписчики не могут заранее определить URI для подписки, поскольку URI будет существовать лишь после восприятия RPC establish-subscription. Поэтому POST для RPC establish-subscription применяется вместо GET для листа location, используемого в [RFC8040] для получения URI. Идентификатор URI для подписки определяется и передаётся как часть отклика на RPC establish-subscription и последующая операция GET для этого URI запускает процесс отправки уведомлений подписчику. Как указано в параграфе 2.4.1 [RFC8639], подписка не активируется до получения GET.

3.1. Транспортная связность

При отсутствии организованной ранее сессии RESTCONF для динамической подписки подписчик инициирует новую сессию RESTCONF. Как указано в параграфе 2.1 [RFC8040], подписчик должен организовать сессию HTTP с применением TLS [RFC8446] для защиты передаваемого содержимого.

Без привлечения дополнительных протоколов сессии HTTP не способны быстро обнаруживать потерю связности с издателем. Когда нужно быстро распознавать такую потерю, подписчику следует использовать TLS heartbeat [RFC6520] для отслеживания связности сессии HTTP. Потеря heartbeat должна приводить к разрыву всех связанных с подпиской сессий TCP между конечными точками. После этого подписчик может попытаться заново организовать подписку с использованием процедуры из параграфа 3.4.

3.2. Обнаружение

Подписчики могут узнать поддерживаемые сервером RESTCONF потоки событий, запросив контейнер streams из модуля ietf-subscribed-notifications.yang [RFC8639]. Поддержка контейнера streams из модуля ietf-restconf-monitoring.yang [RFC8040] не требуется. В случае использования заданной здесь привязки RESTCONF для доставки контейнера streams из модуля ietf-restconf-monitoring.yang (функция поддерживается) предполагается наличие всех содержащихся в нем потоков событий в контейнере streams из модуля ietf-restconf-monitoring.yang.

Подписчики могут узнать поддерживаемые сервером RESTCONF хранилища данных в соответствии с разделом 2 в [RFC8527].

3.3. RESTCONF RPC и коды состояния HTTP

Коды отклика HTTP, заданные в разделе 6 [RFC7231], будут указывать результат запроса RESTCONF RPC к издателю. Отклик HTTP с кодом 200 говорит об успешном выполнении RPC, заданных в [RFC8639] или [RFC8641].

Если у издателя возникает отказ при выполнении запроса RPC по одной или нескольким причинам, указанным в параграфе 2.4.6 [RFC8639] или Приложении A к [RFC8641], это указывается соответствующим кодом ошибки в отклике HTTP, как показано ниже. При возврате кода ошибки HTTP отклик RPC должен включать элемент <rpc-error> в соответствии с параграфом 7.1 [RFC8040], включающий указанные ниже параметры.

Узел error-type из application.
Узел error-tag, значением которого является строка, соответствующая связанному с ошибкой идентификатору. Значение error-tag соответствует идентификаторам ошибок из параграфа 2.4.6 в [RFC8639] для базовых ошибок (Таблица 1) или Приложения A.1 к [RFC8641] для ошибок, связанных с хранилищем YANG (Таблица 2).
Узел error-app-tag, значением которого является строка, соответствующая связанному с ошибкой идентификатору, как указано в параграфе 2.4.6 [RFC8639] для базовых ошибок или Приложении A.1 к [RFC8641] для ошибок подписки, связанных с хранилищами YANG. Применяемый тег зависит от вызова RPC, связанного с ошибкой (Таблица 3).

Таблица 1. Идентификаторы и теги базовых ошибок.

Идентификатор ошибки	error-tag	Код HTTP
dscp-unavailable	invalid-value	400
encoding-unsupported	invalid-value	400
filter-unsupported	invalid-value	400
insufficient-resources	resource-denied	409
no-such-subscription	invalid-value	404
replay-unsupported	operation-not-supported	501

Таблица 2. Идентификаторы и теги ошибок связанных с хранилищем данных.

Идентификатор ошибки	error-tag	Код HTTP
cant-include	operation-not-supported	501
datastore-not-subscribable	invalid-value	400
no-such-subscription-resync	invalid-value	404
on-change-unsupported	operation-not-supported	501
on-change-sync-unsupported	operation-not-supported	501
period-unsupported	invalid-value	400
update-too-big	too-big	400
sync-too-big	too-big	400
unchanging-selection	operation-failed	500

Таблица 3. Идентификаторы и теги ошибок RPC.

RPC	Базовый идентификатор
establish-subscription	establish-subscription-error
modify-subscription	modify-subscription-error
delete-subscription	delete-subscription-error
kill-subscription	delete-subscription-error
resync-subscription	resync-subscription-error

Каждый идентификатор ошибки будет помещаться как error-app-tag с использрванием кодирования JSON в форме <modulename>:<identityname>, например, ietf-subscribed-notifications:no-such-subscription.

При ошибке для запроса establish-subscription или modify-subscription имеется возможность включить узел error-info, который может содержать рекомендации для параметров, позволяющих предотвратить ошибку при последующем вызове RPC. В таблицах 4 и 5 показаны структуры yang-data, которые могут быть возвращены.

Таблица 4. Необязательные советы error-info для запроса establish-subscription.

Цель	Возвращается в структуре yang-data
Поток событий	establish-subscription-stream-error-info
Хранилище	establish-subscription-datastore-error-info

Таблица 5. Необязательные советы error-info для запроса modify-subscription.

Цель	Возвращается в структуре yang-data
Поток событий	modify-subscription-stream-error-info
Хранилище	modify-subscription-datastore-error-info

В yang-data внутри error-info не следует включать необязательный лист reason, поскольку он будет избыточным (все сведения уже присутствуют в error-app-tag).

Для <rpc-error> в результате ошибки при запроск delete-subscription, kill-subscription или resync-subscription не требуется включать error-info, поскольку subscription-id является единственным входным параметром RPC и давать какие-либо советы по входняс параметрам RPC не имеет смысла.

Отметим, что error-path [RFC8040] не требуется включать в элемент <rpc-error>, поскольку ошибки обычно связаны с выбором входных параметров RPC.

3.4. Поток вызовов для событий SSE

Поток вызовов для передаваемых сервером событий (Server-Sent Events или SSE) показан на рисунке 1. Логическими соединениями (a) и (b) могут быть соединения TCP или потоки HTTP/2 (при использовании HTTP/2 в одном соединении TCP может существовать несколько потоков HTTP/2). Запросы RPC, заданные в [RFC8639] или [RFC8641], передаются через соединение (a). Успешное выполнение establish-subscription будет приводить к отклику RPC с идентификатором подписки и URI с однозначным указанием местоположения подписки у издателя (b). Идентификатор URI задан листом uri в модели данных раздела 7.

HTTP GET передаётся через отдельное логическое соединение (b) с URI у издателя. Это указывает издателю, что нужно инициировать поток уведомлений, передаваемых в SSE [W3C-20150203], как отклик на GET. Не может быть передано несколько одновременных запросов GET для URI подписки и каждый запрос GET при обработке GET для того же URI должен отвергаться с кодом HTTP 409.

Как описано в параграфе 6.4 [RFC8040], серверам RESTCONF не следует передавать поля event и id в уведомлениях SSE.

Ниже указаны дополнительные требования к динамическим подпискам через SSE.

Издатель должен возвращать все уведомления о состоянии подписки в отдельном сообщении SSE, используемом подпиской, к которой относятся изменения статуса.
Для RPC подписки недопустимо использовать соединение, через которое в настоящее время передаются уведомления для этой подписки.
В дополнение к отклику на RPC modify-subscription через соединение (a), должно передаваться уведомление о смене состояния subscription-modified через соединение (b). Это позволит получателю точно знать, когда в потоке событий были приенены новые условия подписки (стрелка (c)).
В дополнение к требуемым правам доступа (например, NACM³), RPC modify-subscription, resync-subscription и delete-subscription следует разрешать лишь тому пользователю RESTCONF [RFC8040], который вызвал establish-subscription. Такое ограничение обычно служит для сохранения приватности пользователей, но могут применяться исключения для администраторов, которым может требоваться изменить или удалить подписки других пользователей.
RPC kill-subscription можно вызывать любому пользователю RESTCONF, имеющему права администратора.

+--------------+                             +--------------+
|   Пописчик   |                             |   Издатель   |
|              |                             |              |
|  Логическое  |                             |  Логическое  |
|  соединение  |                             |  соединение  |
|  (a)  (b)    |                             |    (a)  (b)  |
+--------------+                             +--------------+
    | RESTCONF POST (RPC:establish-subscription)   |
    |--------------------------------------------->|
    |                          HTTP 200 OK (ID,URI)|
    |<---------------------------------------------|
    |    |HTTP GET (URI)                                |
    |    |--------------------------------------------->|
    |    |                                   HTTP 200 OK|
    |    |<---------------------------------------------|
    |    |                           SSE (notif-message)|
    |    |<---------------------------------------------|
    | RESTCONF POST (RPC:modify-subscription)      |    |
    |--------------------------------------------->|    |
    |    |                              HTTP 200 OK|    |
    |<---------------------------------------------|    |
    |    |                   SSE (subscription-modified)|
    |    |<------------------------------------------(c)|
    |    |                           SSE (notif-message)|
    |    |<---------------------------------------------|
    | RESTCONF POST (RPC:delete-subscription)      |    |
    |--------------------------------------------->|    |
    |    |                              HTTP 200 OK|    |
    |<---------------------------------------------|    |
    |    |                                         |    |
    |    |                                         |    |
   (a)  (b)                                       (a)  (b)

Рисунок 1. Динамическая подписка с событиями SSE.

Издатель должен прерывать подписку в случае:

получения для неё RPC delete-subscription или kill-subscription;
потери TLS heartbeat.

Издатель может прервать подписку в любой момент, как указано в параграфе 1.3 [RFC8639].

4. Трактовка QoS

Обработка Qos для потока событий описана в параграфе 2.3 [RFC8639]. При использовании HTTP/2 издатель дополнительно должен соблюдать указанное ниже.

Принимать лист weighting [RFC8639] и копировать его в вес потока HTTP/2 (параграф 5.3 в [RFC7540]).
Принимать имеющиеся для подписки зависимости из листа dependency [RFC8639] и использовать поток HTTP/2 родительской подписки как зависимость потока HTTP/2 (параграф 5.3.1 в [RFC7540]) для зависимой подписки.
Сбросить (0) флаг исключительности (exclusive, параграф 5.3.1 в [RFC7540]).

Для динамических подписок с одним кодом дифференцированного обслуживания (Differentiated Services Code Point или DSCP) у конкретного издателя, подписчику рекомендуется передавать все запросы GET для URI в одной сессии HTTP/2 (если применяется HTTP/2). Для разных кодов DSCP подписчик не может использовать одну сессию HTTP/2.

5. Уведомления

Уведомления, доставляемые по протоколу RESTCONF, кодируются в соответствии с параграфом 6.4 [RFC8040].

6. Дерево YANG

Модуль YANG, заданный в разделе 7, имеет лист, дополняющий три узла из [RFC8639].

   module: ietf-restconf-subscribed-notifications
     augment /sn:establish-subscription/sn:output:
       +--ro uri?   inet:uri
     augment /sn:subscriptions/sn:subscription:
       +--ro uri?   inet:uri
     augment /sn:subscription-modified:
       +--ro uri?   inet:uri

7. Модуль YANG

Этот модуль ссылается на [RFC8639].

   <CODE BEGINS>
     file "ietf-restconf-subscribed-notifications@2019-11-17.yang"
   module ietf-restconf-subscribed-notifications {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:"
             + "ietf-restconf-subscribed-notifications";
     prefix rsn;

     import ietf-subscribed-notifications {
       prefix sn;
     }
     import ietf-inet-types {
       prefix inet;
     }

     organization
       "IETF NETCONF (Network Configuration) Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/netconf/> 
        WG List:  <mailto:netconf@ietf.org> 

        Editor:   Eric Voit
                  <mailto:evoit@cisco.com> 

        Editor:   Alexander Clemm
                  <mailto:ludwig@clemm.org> 

        Editor:   Reshad Rahman
                  <mailto:rrahman@cisco.com>"; 
     description
       "Задаёт RESTCONF как транспорт для уведомлений по подписке.

        Авторские права (Copyright (c) 2019) принадлежат IETF Trust и
        лицам, указанным как авторы. Все права защищены.

        Распространение и применение модуля в исходной или двоичной 
        форме с изменениями или без таковых разрешено в соответствии с
        лицензией Simplified BSD License, изложенной в параграфе 4.c
        IETF Trust's Legal Provisions Relating to IETF Documents
        (https://trustee.ietf.org/license-info). 

        Эта версия модуля YANG является частью RFC 8650, где правовые
        аспекты приведены более полно.";

     revision 2019-11-17 {
       description
         "Исходный выпуск";
       reference
         "RFC 8650: Dynamic Subscription to YANG Events and Datastores
          over RESTCONF";
     }

     grouping uri {
       description
         "Описание URI, используемое неоднократно.";
       leaf uri {
         type inet:uri;
         config false;
         description
           "Расположение связанного с подпиской URI у издателя.";
       }
     }

     augment "/sn:establish-subscription/sn:output" {
       description
         "Позволяет использовать связанные с RESTCONF параметры
          для откликов на запросы подписки.";
       uses uri;
     }

     augment "/sn:subscriptions/sn:subscription" {
       description
         "Позволяет раскрывать связанные с RESTCONF параметры
          для подписки.";
       uses uri;
     }

     augment "/sn:subscription-modified" {
       description
         "Позволяет включать связанные с RESTCONF параметры в
          уведомления об изменении подписки.";
       uses uri;
     }
   }
   <CODE ENDS>

8. Взаимодействие с IANA

Этот документ регистрирует URI в субреестре ns реестра IETF XML Registry [RFC3688].

URI:	urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications
Registrant Contact:	The IESG.
XML:	N/A; запрошенный URI является пространством имён XML.

Этот документ регистрирует модуль YANG в реестре YANG Module Names [RFC6020]:

Name:	ietf-restconf-subscribed-notifications
Namespace:	urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications
Prefix:  	rsn
Reference:  	RFC 8650

9. Вопросы безопасности

Описанный в этом документе модуль YANG определяет схему данных, которая предназначения для доступа по протоколам сетевого управления, таким как NETCONF [RFC6241] или RESTCONF [RFC8040]. Нижним уровнем NETCONF является защищённый транспорт с обязательной поддержкой SSH⁴ [RFC6242]. Нижним уровнем RESTCONF является HTTPS с обязательной поддержкой TLS [RFC5246].

Модель управления доступом NETCONF (Network Configuration Access Control Model или NACM) [RFC8341] обеспечивает способы ограничения доступа отдельным пользователям NETCONF или RESTCONF заданным подмножеством всех доступных операций и содержимого NETCONF или RESTCONF.

Один из добавленных модулей YANG узлов данных может быть быть чувствительным или уязвимым в некоторых сетевых средах. Важно контролировать доступ к считыванию этого узла (например, через get, get-config, notification) в контейнере /subscriptions.

uri

Указывает место размещения включённых в подписку ресурсов у издателя. Права доступа должны быть установлены так, чтобы к ресурсу мог обращаться только тот пользователь RESTCONF [RFC8040], который вызвал establish-subscription.

URI подписки зависит от реализации и шифруется с помощью TLS. Даже если атакующему удастся угадать URI, потребуется ещё имя пользователя RESTCONF [RFC8040] с соответствующей аутентификацией для получения доступа к подписке или её изменения. Рекомендуется применять труднопредсказуемые значения URI.

Вопросы прав доступа для RPC modify-subscription, resync-subscription, delete-subscription, kill-subscription рассмотрены в параграфе 3.4.

Если неисправный или скомпрометрированный подписчик RESTCONF может передавать большое число запросов establish-subscription, эти подписки накапливаются и могут отнять много ресурсов системы. В такой ситуации издатель может приостановить или прервать часть активных подписок этого подписчика RESTCONF для возврата ресурсов и обеспечения нормальной работы других подписчиков.

10. Литература

10.1. Нормативные документы

[RFC2119] Bradner, S., «Key words for use in RFCs to Indicate Requirement Levels», BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC3688] Mealling, M., «The IETF XML Registry», BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.

[RFC6020] Bjorklund, M., Ed., «YANG — A Data Modeling Language for the Network Configuration Protocol (NETCONF)», RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.

[RFC6242] Wasserman, M., «Using the NETCONF Protocol over Secure Shell (SSH)», RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.

[RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, «Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) Heartbeat Extension», RFC 6520, DOI 10.17487/RFC6520, February 2012, <https://www.rfc-editor.org/info/rfc6520>.

[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., «Hypertext Transfer Protocol Version 2 (HTTP/2)», RFC 7540, DOI 10.17487/RFC7540, May 2015, <https://www.rfc-editor.org/info/rfc7540>.

[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, «RESTCONF Protocol», RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.

[RFC8174] Leiba, B., «Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words», BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8341] Bierman, A. and M. Bjorklund, «Network Configuration Access Control Model», STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.

[RFC8446] Rescorla, E., «The Transport Layer Security (TLS) Protocol Version 1.3», RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.

[RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, «Subscription to YANG Notifications», RFC 8639, DOI 10.17487/RFC8639, September 2019, <https://www.rfc-editor.org/info/rfc8639>.

[RFC8641] Clemm, A. and E. Voit, «Subscription to YANG Notifications for Datastore Updates», RFC 8641, DOI 10.17487/RFC8641, September 2019, <https://www.rfc-editor.org/info/rfc8641>.

[W3C-20150203] Hickson, I., «Server-Sent Events», W3C Recommendation, 3 February 2015, <https://www.w3.org/TR/2015/REC-eventsource-20150203/>. Latest version available at <https://www.w3.org/TR/eventsource/>.

10.2. Дополнительная литература

[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., «Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content», RFC 7231, DOI 10.17487/RFC7231, June 2014, <https://www.rfc-editor.org/info/rfc7231>.

[RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, «Requirements for Subscription to YANG Datastores», RFC 7923, DOI 10.17487/RFC7923, June 2016, <https://www.rfc-editor.org/info/rfc7923>.

[RFC7951] Lhotka, L., «JSON Encoding of Data Modeled with YANG», RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>.

[RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. Zhang, «A YANG Data Model for the Virtual Router Redundancy Protocol (VRRP)», RFC 8347, DOI 10.17487/RFC8347, March 2018, <https://www.rfc-editor.org/info/rfc8347>.

[RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, «RESTCONF Extensions to Support the Network Management Datastore Architecture», RFC 8527, DOI 10.17487/RFC8527, March 2019, <https://www.rfc-editor.org/info/rfc8527>.

[RFC8640] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, «Dynamic Subscription to YANG Events and Datastores over NETCONF», RFC 8640, DOI 10.17487/RFC8640, September 2019, <https://www.rfc-editor.org/info/rfc8640>.

[XPATH] Clark, J. and S. DeRose, «XML Path Language (XPath) Version 1.0», W3C Recommendation, 16 November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>. Latest version available at <https://www.w3.org/TR/ xpath/>.

Приложение A. Примеры

Это приложение не является нормативным. Для простоты сравнения здесь приведены функциональные примеры, использованные для NETCONF с XML в [RFC8640]. Заголовки HTTP/2 и HTTP/1.1 не приводятся, поскольку содержимое объектов в кодировке JSON идентично им.

Значения URI подписки в примерах являются лишь иллюстративными и не указывают предполагаемого использования, описанного в разделе 9. Значения DSCP приведены лишь для иллюстрации и используют десятичный формат из-за кодировки JSON [RFC7951].

A.1. Динамические подписки

A.1.1. Организация динамической подписки

На рисунке 2 приведены два успешных запроса RPC establish-subscription в соответствии с [RFC8639]. Первый запрос имеет идентификатор 22, второй — 23.

+------------+                  +-----------+
| Подписчик  |                  | Издатель  |
+------------+                  +-----------+
      |                               |
      |establish-subscription         |
      |------------------------------>|  (a)
      |     HTTP 200 OK, id#22, URI#1 |
      |<------------------------------|  (b)
      |GET (URI#1)                    |
      |------------------------------>|  (c)
      | HTTP 200 OK,notif-mesg (id#22)|
      |<------------------------------|
      |                               |
      |                               |
      |establish-subscription         |
      |------------------------------>|
      |      HTTP 200 OK, id#23, URI#2|
      |<------------------------------|
      |GET (URI#2)                    |
      |------------------------------>|
      |                               |
      |                               |
      |             notif-mesg (id#22)|
      |<------------------------------|
      | HTTP 200 OK,notif-mesg (id#23)|
      |<------------------------------|
      |                               |

Рисунок 2. Несколько подписок через RESTCONF/HTTP.

Ниже представлены примеры передаваемой информации для взаимодействий на рисунке 2.

   POST /restconf/operations
        /ietf-subscribed-notifications:establish-subscription

   {
      "ietf-subscribed-notifications:input": {
         "stream-xpath-filter": "/example-module:foo/",
         "stream": "NETCONF",
         "dscp": 10
      }
   }

Рисунок 3. Запрос establish-subscription (a).

Если издатель способен полностью выполнить запрос, он возвращает идентификатор организованной подписки и URI.

   HTTP status code - 200

   {
      "ietf-subscribed-notifications:output": {
         "id": 22,
         "ietf-restconf-subscribed-notifications:uri":
            "https://example.com/restconf/subscriptions/22"
      }
   }⁵

Рисунок 4. Запрос establish-subscription (b).

При получении отклика об успехе подписчик передаёт запрос GET для представленного URI, чтобы запустить поток уведомлений. При пулучении этого запроса издателем подписка переводится в активное состояние (c).

   GET /restconf/subscriptions/22

Рисунок 5. GET после запроса establish-subscription⁶.

Если издатель не может полностью выполнить запрос или у подписчика нет прав на организацию подписки, издатель будет возвращать отклик об ошибке RPC (не показан на рисунке 2). Например, если указанное подписчиком значение dscp 10 (Рисунок 3), оказалось неприемлемым, издатель может возвратить отклик

   HTTP status code - 400

   { "ietf-restconf:errors" : {
       "error" : [
         {
           "error-type": "application",
           "error-tag": "invalid-value",
           "error-severity": "error",
           "error-app-tag":
               "ietf-subscribed-notifications:dscp-unavailable"
         }
       ]
     }
   }

Рисунок 6. Отклик о неудаче establish-subscription.

Подписчик может применить полученные сведения при следующей попытке организовать подписку.

A.1.2. Изменение динамической подписки

Имеющуюся подписку можно изменить. На рисунке 7 показано согласование такого изменения путём обмена между подписчиком и издателем. Согласование включает запрос и отклик для неудачной попытки, затем — удачную подписку.

+------------+                 +-----------+
| Подписчик  |                 | Издатель  |
+------------+                 +-----------+
      |                              |
      |      уведомление (id#23)     |
      |<-----------------------------|
      |                              |
      |modify-subscription (id#23)   |
      |----------------------------->|  (d)
      |   Код HTTP 400 (с сосветом)  |
      |<-----------------------------|  (e)
      |                              |
      |modify-subscription (id#23)   |
      |----------------------------->|
      |                  HTTP 200 OK |
      |<-----------------------------|
      |                              |
      |            notif-mesg (id#23)|
      |<-----------------------------|
      |                              |

Рисунок 7. Модель взаимодействия при успешном изменении подписки.

Если подписка, изменяемая на рисунке 7 относится к хранилищу данных, как в [RFC8641], запрос на изменение (d) может иметь вид, показанный на рисунке 8. Предложенные изменения включают применение нового фильтра XPath (XML Path Language) и установку нового интервала периодической отправки.

   POST /restconf/operations
        /ietf-subscribed-notifications:modify-subscription

   {
    "ietf-subscribed-notifications:input": {
       "id": 23,
       "ietf-yang-push:datastore-xpath-filter":
          "/example-module:foo/example-module:bar",
       "ietf-yang-push:periodic": {
          "ietf-yang-push:period": 500
       }
     }
   }

Рисунок 8. Запрос изменения подписки (c).

Если издатель может выполнить оба запроса, он будет возвращать положительный отклик для RPC. Если какое-либо изменение неприменимо, издатель передаёт отклик об ошибке RPC (e). Ниже представлен пример отклика об ошибке RPC (e), включающего совет, указывающий другой интервал, который может привести к успеху подписки.

   HTTP status code - 400

   { "ietf-restconf:errors" : {
       "error" : [
         "error-type": "application",
         "error-tag": "invalid-value",
         "error-severity": "error",
         "error-app-tag": "ietf-yang-push:period-unsupported",
         "error-info": {
           "ietf-yang-push":
           "modify-subscription-datastore-error-info": {
              "period-hint": 3000
           }
         }
       ]
     }
   }

Рисунок 9. Отказ modify-subscription с советом (e).

A.1.3. Удаление динамической подписки

Ниже показано удаление подписки (поток событий или хранилище).

   POST /restconf/operations
        /ietf-subscribed-notifications:delete-subscription
   {
    "ietf-subscribed-notifications:input": {
       "id": "22"
    }
   }⁷

Рисунок 10. Запрос delete-subscription.

Если издатель может выполнить запрос, он возвращает положительный отклик на запрос RPC.

Если издатель не может выполнить запрос, он передаёт элемент <rpc-error>, указывающий, что удаление не прошло. На рисунке 11 показан отклик для действительного идентификатора подписки, но созданного в другой транспортной сессии.

   HTTP status code - 404
   {
     "ietf-restconf:errors" : {
       "error" : [
         "error-type": "application",
         "error-tag": "invalid-value",
         "error-severity": "error",
         "error-app-tag":
            "ietf-subscribed-notifications:no-such-subscription"
       ]
     }
   }

Рисунок 11. Неудача delete-subscription.

A.2. Уведомления о статусе подписки

Издатель будет передавать уведомления о состоянии подписки в соответствии с определениями [RFC8639].

A.2.1. subscription-modified

Уведомление subscription-modified в кодировке JSON будет иметь вид

   {
     "ietf-restconf:notification" : {
       "eventTime": "2007-09-01T10:00:00Z",
       "ietf-subscribed-notifications:subscription-modified": {
         "id": 39,
         "uri": "https://example.com/restconf/subscriptions/39"
         "stream-xpath-filter": "/example-module:foo",
         "stream": {
            "ietf-netconf-subscribed-notifications" : "NETCONF"
         }
       }
     }
   }⁸

Рисунок 12. Уведомление о состоянии подписки subscription-modified.

A.2.2. subscription-completed, subscription-resumed, replay-completed

Уведомление subscription-completed будет иметь вид

   {
     "ietf-restconf:notification" : {
       "eventTime": "2007-09-01T10:00:00Z",
       "ietf-subscribed-notifications:subscription-completed": {
         "id": 39,
       }
     }
   }

Рисунок 13. Уведомление subscription-completed в кодировке JSON.

Уведомления subscription-resumed и replay-complete практически идентичны, просто subscription-completed заменяется на subscription-resumed и replay-complete.

A.2.3. subscription-terminated и subscription-suspended

Уведомление subscription-terminated будет иметь вид

   {
     "ietf-restconf:notification" : {
       "eventTime": "2007-09-01T10:00:00Z",
       "ietf-subscribed-notifications:subscription-terminated": {
         "id": 39,
         "error-id": "suspension-timeout"
       }
     }
   }

Рисунок 14. Уведомление о смене состояния subscription-terminated.

Уведомление subscription-suspended практически идентично subscription-terminated с соответствующей заменой.

A.3. Пример фильтра

В этом параграфе приведён пример, иллюстрирующий метод фильтрации содержимого записей о событиях. Пример основан уведомлении YANG vrrp-protocol-error-event, заданном в модуле ietf-vrrp.yang [RFC8347]. Записи о событиях, создаваемые издателем на основе этой спецификации могут иметь вид

   data: {
   data:   "ietf-restconf:notification" : {
   data:     "eventTime" : "2018-09-14T08:22:33.44Z",
   data:     "ietf-vrrp:vrrp-protocol-error-event" : {
   data:       "protocol-error-reason" : "checksum-error"
   data:     }
   data:   }
   data: }

Рисунок 15. RFC 8347 (VRRP) — пример уведомления.

Предположим, что подписчик хочет получать лишь записи о событиях, содержащие checksum-error в записи о событии протокола резервирования виртуального маршрутизатора (Virtual Router Redundancy Protocol или VRRP). Пусть издатель помещает такие записи о событиях в поток NETCONF. Для получения последовательнсти соответствующих записей подписчик может запросить применение фильтра XPath к потоку NETCONF. RPC establish-subscription для этого может иметь вид

   POST /restconf/operations
        /ietf-subscribed-notifications:establish-subscription
   {
      "ietf-subscribed-notifications:input": {
         "stream": "NETCONF",
         "stream-xpath-filter":
           "/ietf-vrrp:vrrp-protocol-error-event[
             protocol-error-reason='checksum-error']/",
      }
   }

Рисунок 16. Указание ошибки при подписке через XPath.

Дополнительные примеры фильтров XPath приведены в [XPATH].

Предположим, что запрос establish-subscription (Рисунок 16) воспринят, а затем подписчик решил расширить подписку для охвата всех событий протокола VRRP (т. е., не только с checksum error). Подписчик может попытаться изменить подписку путём замены фильтра XPath фильтром ветвей, который будет передавать подписчику все события протокола VRRP. Такой вызов RPC modify-subscription может иметь вид

   POST /restconf/operations
        /ietf-subscribed-notifications:modify-subscription
   {
      "ietf-subscribed-notifications:input": {
         "stream": "NETCONF",
         "stream-subtree-filter": {
           "/ietf-vrrp:vrrp-protocol-error-event" : {}
         }
      }
   }

Рисунок 17. Пример RPC modify-subscription.

Дополнительные фильтры ветвей можно найти в параграфе 6.4 [RFC6241].

Благодарности

Спасибо Ambika Prasad Tripathy, Alberto Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu, Robert Wilton за полезный вклад, комментарии и предложения.

Адреса авторов

Eric Voit

Cisco Systems

Email: evoit@cisco.com

Reshad Rahman

Cisco Systems

Email: rrahman@cisco.com

Einar Nilsen-Nygaard

Cisco Systems

Email: einarnn@cisco.com

Alexander Clemm

Futurewei

Email: ludwig@clemm.org

Andy Bierman

YumaWorks

Email: andy@yumaworks.com

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Internet Engineering Task Force — комиссия по решению инженерных задач Internet.

2Internet Engineering Steering Group — комиссия по инженерным разработкам Internet.

3Network Configuration Access Control Model — модель управления доступом к настройке сети.

4Secure Shell — защищённая оболочка.

5В оригинале этот фрагмент был указан с ошибкой. См. https://www.rfc-editor.org/errata/eid6985. Прим. перев.

6В оригинале ошибочно указано POST. См. https://www.rfc-editor.org/errata/eid6379. Прим. перев.

7В оригинале этот фрагмент был указан с ошибкой. См. https://www.rfc-editor.org/errata/eid6985. Прим. перев.

8В оригинале этот фрагмент был указан с ошибкой. См. https://www.rfc-editor.org/errata/eid6369. Прим. перев.

Рубрика: RFC | Оставить комментарий

Программа для анализа производительности — perf

Опубликовано 21.10.2019 автором Nikolai Malykh

PDF

Счетчики Linux образуют основанную на возможностях ядра подсистему, позволяющую анализировать производительность различных операций в ядре и пользовательском пространстве. Они охватывают аппаратный уровень (CPU/PMU¹) и программные компоненты (счетчики, точки прерывания).

Синтаксис

perf [--version] [--help] [OPTIONS] COMMAND [ARGS]

Опции

—debug

Устанавливает для отладочных переменных значения от 0 до 10, позволяя устанавливать перечисленные ниже переменные. Большее значение задает более подробный вывод.
verbose — базовые отладочные сообщения;
ordered-events — отладочные сообщения упорядоченных событий;
data-convert — отладочные сообщения команд преобразования данных;
stderr — запись отладочных сообщений (опция -v) на stderr в режиме браузера.

—buildid-dir

Задает каталог кэширования идентификаторов сборки (эта опция имеет более высокий приоритет по сравнению с переменной buildid.dir в файле конфигурации).

-v, —version

Выводит версию программы perf.

-h, —help

Выводит справку о команде perf.

Команды

bench

Общая база для тестов производительности.

Синтаксис

perf bench [<common options>] <subsystem> <suite> [<options>]

Опции общего назначения

-r, —repeat=

Задает число повторения тестов (по умолчанию 10).

-f, —format=

Задает стиль форматирования вывода.

default

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

          % perf bench sched pipe                      # стиль не задан
          (executing 1000000 pipe operations between two tasks) 
                  Total time:5.855 sec 
                          5.855061 usecs/op 
                          170792 ops/sec

simple

Упрощенный стиль, удобный для обработки в программных сценариях.

          % perf bench --format=simple sched pipe      # заданный стиль
          5.988

Подсистемы

sched

Механизмы планировщиков и IPC².

mem

Производительность доступа к памяти.

numa

Планирование NUMA³ и производительность MM.

futex

Стрессовые тесты Futex.

epoll

Стрессовые тесты опроса событий (epoll).

all

Все подсистемы тестирования.

Тесты для sched

messaging

Набор тестов для оценки производительности механизмов планирования и IPC, основанный на разработках Rusty Russell.

Опции messaging

-p, —pipe

Использовать pipe() вместо socketpair().

-t, —thread

Использовать множество потоков (thread) вместо множества процессов.

-g, —group=

Задает число групп.

-l, —nr_loops=

Задает число циклов.

Пример messaging

              % perf bench sched messaging                 # параметры по умолчанию
              options (20 sender and receiver processes per group) 
              (10 groups == 400 processes run) 

                    Total time:0.308 sec 

              % perf bench sched messaging -t -g 20        # множество потоков, 20 групп
              (20 sender and receiver threads per group) 
              (20 groups == 800 threads run) 

                    Total time:0.582 sec

pipe

Тесты для системных вызовов pipe() на основе pipe-test-1m.c от Ingo Molnar.

Опции pipe

-l, —loop=

Задает число циклов.

Пример pipe

              % perf bench sched pipe 
              (executing 1000000 pipe operations between two tasks) 

                      Total time:8.091 sec 
                              8.091833 usecs/op 
                              123581 ops/sec 

              % perf bench sched pipe -l 1000              # loop 1000 
              (executing 1000 pipe operations between two tasks) 

                      Total time:0.016 sec 
                              16.948000 usecs/op 
                              59004 ops/sec

Тесты для mem

memcpy

Набор тестов для оценки скорости простых операций копирования в памяти различными способами.

Опции memcpy

-l, —size

Размер копируемого блока (по умолчанию 1 Мбайт). Задается числом с суффиксом B, KB, MB, GB или TB (без учета регистра символов).

-f, —function

Задает функцию копирования (по умолчанию default). Доступные функции зависят от архитектуры, для x86-64 поддерживаются x86-64-unrolled, x86-64-movsq и x86-64-movsb.

-l, —nr_loops

Задает повтор вызова memcpy указанное число раз.

-c, —cycles

Задает использование perf события cpu-cycles вместо системного вызова gettimeofday.

memset

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

Опции для memset

-l, —size

-f, —function

Задает функцию копирования (по умолчанию default). Доступные функции зависят от архитектуры, для x86-64 поддерживаются x86-64-unrolled, x86-64-stosq и x86-64-stosb.

-l, —nr_loops

Задает повтор вызова memset указанное число раз.

-c, —cycles

Задает использование perf события cpu-cycles вместо системного вызова gettimeofday.

Тесты для numa

mem

Набор тестов для оценки выполнения заданий NUMA.

Тесты для futex

hash

Тесты для оценки хэш-таблиц.

wake

Тесты для оценки вызовов wake.

wake-parallel

Тесты для оценки параллельных вызовов wake.

requeue

Тесты для оценки вызовов requeue.

lock-pi

Тесты для оценки вызовов futex lock_pi.

Опции для всех тестов

-S, —shared

Использовать вызовы общих futex вместо приватных.

-s, —silent

Без вывода данных и деталей.

-t, —threads <n>

Задает число потоков (thread)

Опции для отдельных тестов

-f, —futexes <n>

Задает число вызовов futex на поток (только hash).

-r, —runtime <n>

Задает время работы в секундах (hash и lock-pi).

-w, —nwakes <n>

Задает число потоков для разового пробуждения (wake и wake-parallel)

-q, —nrequeue <n>

Задает число потоков для разового изменения очередности (только requeue).

-M, —multi

Использовать множество futex (только lock-pi).

Тесты для epoll

wait

Тесты для оценки одновременных вызовов epoll_wait.

ctl

Тесты для оценки множества вызовов epoll_ctl.

Опции для всех тестов

-f, —nfds <n>

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

-N, —nested <n>

Задает уровень вложенности для иерархии epoll (по умолчанию без вложенности — 0).

-n, —noaffinity

Отключает близость CPU (affinity).

-R, —randomize

Задает выполнение случайных операций на случайных дескрипторах файлов.

-r, —runtime <n>

Задает время работы в секундах.

-t, —threads <n>

Задает число потоков (thread).

-v, —verbose

Расширенный вывод

Опции для wait

-B, —nonblocking

Неблокируемое поведение epoll_wait.

-E, —edge

использовать интерфейс Edge-triggered (по умолчанию LT).

-m, —multiq

Использовать множество экземпляров epoll (по одному на поток).

-S, —oneshot

Использовать семантику EPOLLONESHOT

stat

Выполняет указанную параметром команду, собирая статистику работы.
Синтаксис

perf stat [-e <EVENT> | --event=EVENT] [-a] <command> 
perf stat [-e <EVENT> | --event=EVENT] [-a] - <command> [<options>] 
perf stat [-e <EVENT> | --event=EVENT] [-a] record [-o file] - <command> [<options>] 
perf stat report [-i file]

Опции

<command>…

Любая команда, которая может быть выполнена в консоли.

record

См. Запись статистики (record)

report

См. Статистический отчет (report)

-e, —event=

Задает событие PMU, позволяя выбирать указанные ниже варианты.

Символическое имя события (perf list позволяет увидеть список всех событий).
Необработанное событие PMU (eventsel+umask) в форме rNNN, где NNN является шестнадцатеричным дескриптором события.
Символически сформированное имя вида pmu/param1=0x3,param2/, где param1 и param2 определены как форматы для PMU в файлах /sys/bus/event_source/devices/<pmu>/format/*. Классификатор percore задает суммирование счетчиков для обоих аппаратных потоков (thread) в ядре. Например,
```
perf stat -A -a -e cpu/event,percore=1/,otherevent ...
```
Символически сформированное имя вида pmu/config=M,config1=N,config2=K/, где M, N, K — числа в десятичном, шестнадцатеричном или восьмеричном формате. Приемлемые значения параметров config, config1 и config2 определяются записями в файлах /sys/bus/event_source/devices/<pmu>/format/*

Отметим, что два последних варианта поддерживают префиксы и шаблоны (glob) в именах PMU для упрощенного указания событий во множестве экземпляров одного PMU в больших системах (например, PMU контроллера памяти). Множественные экземпляры типичны для неосновных PMU, поэтому при сопоставлении префикс uncore_ не принимается во внимание.

-i, —no-inherit

Дочерние задачи не наследуют счетчики.

-p, —pid=<pid>

События для процесса с заданными идентификаторами (список разделенных запятыми значений).

-t, —tid=<tid>

События для потоков (thread) с заданными идентификаторами (список разделенных запятыми значений).

-a, —all-cpus

Сбор в масштабе системы от всех CPU (используется по умолчанию, если цель не задана).

—no-scale

Отключает масштабирование и нормализацию значений счетчиков.

-d, —detailed

Задает уровень детализации вывода:
-d — подробные события, кэш данных L1 и LLC;
-d -d — более подробные события, dTLB и iTLB;
-d -d -d — максимально подробные события, добавление событий предварительной выборки.

-r, —repeat=<n>

Повтор команды заданное число раз (не более 100) с усреднением и указанием стандартного отклонения. 0 означает бесконечный повтор.

-B, —big-num

Задает вывод больших чисел с отделением тысяч в соответствии с установками locale.

-C, —cpu=

Задает учет лишь указанных CPU, которые можно задать номерами через запятые без пробелов (0,1) или как диапазон (0-2). В режиме учета по потокам эта опция игнорируется. Для мониторинга в масштабе системы сохраняется актуальность опции -a. По умолчанию учитываются все процессоры.

-A, —no-aggr

Отключает агрегирование счетчиков для отслеживаемых CPU.

-n, —null

Пустой прогон без запуска счетчиков.

-v, —verbose

Задает подробный вывод (показывает ошибки открытия счетчиков и т. п.).

-x SEP, —field-separator SEP

Задает вывод счетчиков с использованием стиля CSV для упрощения импорта в электронные таблицы. Колонки разделяются строкой, заданной параметром SEP.

—table

Задает вывод времени для каждого запуска (опция -r) в форме таблицы. Например, по команде

$ perf stat --null -r 5 --table perf bench sched pipe

Будут выведены счетчики статистики для 5 запусков perf bench sched pipe и общий результат

# Table of individual measurements: 
5.189 (-0.293) # 
5.189 (-0.294) #
5.186 (-0.296) # 
5.663 (+0.181) ## 
6.186 (+0.703) #### 

# Final result: 
5.483 +- 0.198 seconds time elapsed  ( +-  3.62% )

-G name, —cgroup name

Задает отслеживание лишь контейнера (cgroup) с именем name. Эта опция доступна лишь в режиме отслеживания по процессорам (per-cpu). Файловая система cgroup должна быть примонтирована. Все потоки, относящиеся в контейнеру name, будут отслеживаться при работе на контролируемых CPU. Можно указать несколько cgroup, каждая из которых будет применяться к соответствующему событию, т. е. первая cgroup будет применяться к первому событию, вторая — ко второму и т. д. Можно представить пустую cgroup (отслеживается все время), используя, например, -G foo,,bar. Группы cgroup должны иметь соответствующие события, т. е. они всегда указывают на события, определенные ранее в командой строке. Если нужно отслеживать множество событий для определенной cgroup, можно использовать -e e1 -e e2 -G foo,foo или просто -e e1 -e e2 -G foo.

Если нужно отслеживать, например, cycles для cgroup, а также для всей системы, можно воспользоваться командой perf stat -e cycles -G cgroup_name -a -e cycles.

-o file, —output file

Задает вывод данных в указанный файл.

—append

Задает добавление вывода в конец файла, заданного опцией -o (без этой опции игнорируется).

—log-fd

Задает вывод в файл с дескриптором fd вместо stderr и является взаимоисключающей с опцией -output. Позволяет использовать также опцию —append.

—pre, —post

Задает «ловушки» перед измерением и после него.

-I msecs, —interval-print msecs

Задает вывод приращения счетчиков каждые N мсек (минимум 1). В некоторых случаях издержки могут быть велики (например, при интервалах меньше 100 мсек). Опцию следует применять с осторожностью.

—interval-count times

Задает вывод приращения счетчиков фиксированное число раз. Эту опцию следует применять вместе с -I. Например, perf stat -I 1000 —interval-count 2 -e cycles -a.

—interval-clear

Задает очистку экрана перед следующим интервалом.

—timeout msecs

Останавливает сеанс статистики perf и выводит приращения счетчиков по истечении N мсек (минимум 10). Не поддерживается с опцией -I.

—metric-only

Задает вывод только расчетных параметров (в одну строку). Не поддерживается с опцией —per-thread.

—per-socket

Объединяет счетчики отдельных физических процессоров для измерений в масштабе системы. Это полезно для обнаружения разбалансировки между процессорами. Для включения режима опция —per-socket дополняется опцией -a. Вывод включает номер процессора и число активных ядер в нем.

—per-core

Объединяет счетчики ядер отдельных физических процессоров. Это полезно для обнаружения разбалансировки между ядрами. Для включения режима опция —per-core дополняется опцией -a. Вывод включает номер ядра и число активных логических процессоров на данном физическом процессоре.

—per-thread

Объединяет счетчики отслеживаемых потоков (thread) при мониторинге потоков (-t) или процессоров (-p).

-D msecs, —delay msecs

Задает ожидание перед началом измерений после запуска программы. Это полезно для исключения стартовой фазы программы, которая зачастую отличается от основного процесса.

-T, —transaction

Выводит статистику выполнения транзакций, если они поддерживаются.

Запись статистики (record)

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

-o file, —output file

задает имя выходного файла.

Статистический отчет (report)

Считывает данные и выводит отчет на основании файла данных perf.

-i file, —input file

Имя входного файла данных.

—per-socket

Объединение счетчиков по физическим процессорам для измерений в масштабе системы.

—per-core

Объединение счетчиков по ядрам одного физического процессора для измерений в масштабе системы.

-M, —metrics⁴

Задает вывод параметров или групп параметров, указанных в разделенном запятыми списке. Для группы добавляются все параметры данной группы. События для параметров учитываются автоматически. Возможные параметры и группы можно увидеть с помощью команды perf list.

-A, —no-aggr

Отключает объединение данных для всех отслеживаемых CPU.

—topdown¹

Выводит параметры метрики уровня 1, сообщая об узких местах при обработке, если это поддерживается процессором. Это позволяет найти узкие места в конвейере CPU для привязанных к CPU заданий путем разрыва циклов, связанных с пользовательскими (frontend) или аппаратными (backend) ограничениями, неверными предсказаниями (bad speculation) и сокрытием (retiring).

Пользовательское ограничение (Frontend bound) означает, что CPU не может извлекать и декодировать инструкции достаточно быстро. Аппаратное ограничение (Backend bound) говорит об узких местах в расчетах или доступе к памяти. Неверные предсказания (Bad Speculation) указывают на то, что CPU использует ненужные циклы в результате ошибочного предсказания ветвлений и т. п. Retiring означает, что CPU работает без явных узких мест. Узкое место является реальной пробкой лишь в том случае, когда задание действительно ограничено CPU, а не чем-то иным.

Для получения лучших результатов обычно хорошо применять интервал -I 1000, поскольку узкие места в заданиях могут меняться достаточно часто.

Параметры узких мест собираются на уровне ядер, а не потоков CPU. Режим работы на уровне ядер включается автоматически и нужна опция -a (глобальный мониторинг), что требует полномочий root или установки perf.perf_event_paranoid=-1.

Режим topdown полностью использует блок PMU и нужно отключить NMI watchdog (от имени root) командой echo 0 > /proc/sys/kernel/nmi_watchdog для получения лучших результатов. В противном случае могут возникать пробки, не совместимые с рабочей нагрузкой.

Эта опция включает режим —metric-only, если нет опции —no-metric-only.

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

—no-merge⁵

Отменяет слияние результатов от одного PMU.

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

Множество событий создается по одной спецификации, если (1) префикс или регулярное выражение glob применяется для имени PMU или (2) используются псевдонимы, указанные после событий Kernel PMU.

—smi-cost²

Измерение стоимости SMI⁶, если поддерживаются события msr/aperf/ и msr/smi/. В процессе измерения устанавливается опция в файле /sys/device/cpu/freeze_on_smi для замораживания счетчиков при SMI. Эта установке не влияет на счетчик aperf и стоимость SMI может быть измерена (aperf — непрерванные циклы ядра).

На практике процент циклов SMI очень полезен для ориентированного на производительность анализа. По умолчанию применяется опция —metric_only. Выходом является % циклов SMI, равный (aperf — непрерванные циклы ядра) / aperf.

При желании получить актуальное значение можно воспользоваться опцией —no-metric-only.

Пример

$ perf stat make 
[...]
Performance counter stats for 'make': 

             83723.452481      task-clock:u (msec)       #    1.004 CPUs utilized 
                        0      context-switches:u        #    0.000 K/sec 
                        0      cpu-migrations:u          #    0.000 K/sec 
                3,228,188      page-faults:u             #    0.039 M/sec 
          229,570,665,834      cycles:u                  #    2.742 GHz 
          313,163,853,778      instructions:u            #    1.36  insn per cycle 
           69,704,684,856      branches:u                #  832.559 M/sec 
            2,078,861,393      branch-misses:u           #    2.98% of all branches 

          83.409183620 seconds time elapsed 

          74.684747000 seconds user 
           8.739217000 seconds sys

В этом примере видны три типа временных показателей. Всегда выводится время, в течение которого счетчики были включены (активны)

          83.409183620 seconds time elapsed

Для сеансов рабочей нагрузки указывается также время, затраченное в пользовательском и системном пространстве

          74.684747000 seconds user 
           8.739217000 seconds sys

Эти значения совпадают с выводимыми утилитой time.

Формат CSV

С опцией -x команда perf stat будет выводить результаты в формате CSV. Запятые при выводе не будут помещаться в кавычки. Для упрощения анализа вывода рекомендуется использовать с опцией -x другие разделители (например, \;).

Поля выводятся в следующем порядке:

необязательная временная метка (в мксек) в дробной части секунд (с -I xxx);
необязательный идентификатор CPU, ядра или сокета;
необязательное число агрегированных логических CPU;
значение счетчика;
единица измерения счетчика или пустое значение;
имя события;
время работы счетчика;
доля времени измерения от времени работы счетчика (%);
необязательное отклонение при сборе множества значений с опцией -r;
необязательное значение параметра;
необязательная единица измерения параметра.

После этих полей могут выводиться дополнительные параметры.

top

Создание и вывод профиля производительности в реальном масштабе времени.

Синтаксис

perf top [-e <EVENT> | --event=EVENT] [<options>]

Опции

-a, —all-cpus

Сбор данных на уровне системы в целом (используется по умолчанию)

-c <count>, —count=<count>

Период выборки событий.

-C <cpu-list>, —cpu=<cpu>

Отслеживание только указанных CPU. Процессоры можно задать списком разделенных запятыми идентификаторов (без пробелов, 0,1) или диапазоном (0-2). По умолчанию отслеживаются все CPU.

-d <seconds>, —delay=<seconds>

Интервал обновления в секундах.

-e <event>, —event=<event>

Задает событие PMU, которое может быть указано символьным именем (см. perf list) или необработанным (raw) событием PMU (eventsel+umask) в форме rNNN, где NNN — шестнадцатеричный дескриптор события.

-E <entries>, —entries=<entries>

Задает вывод указанного числа функций.

-f <count>, —count-filter=<count>

Задает вывод лишь функций, где число событий превосходит заданное значение.

—group

Задает группировку счетчиков.

-F <freq>, —freq=<freq>

Задает частоту профилирования. Для профилирования с максимально возможной частотой используется значение max, т. е. частота, указанная в kernel.perf_event_max_sample_rate (sysctl).

-i, —inherit

Дочерние задачи не наследуют счетчики.

-k <path>, —vmlinux=<path>

Путь к файлу vmlinux, требуемый для аннотирования.

—ignore-vmlinux

Задает игнорирование файлов vmlinux.

—kallsyms=<file>

Указывает путь к файлу kallsyms.

-m <pages>, —mmap-pages=<pages>

Число страниц данных mmap (должно быть степенью 2) или размер с суффиксом, указывающим единицы (B/K/M/G). Размер округляется до ближайшего значения, равного степени 2.

-p <pid>, —pid=<pid>

События профиля для имеющихся идентификаторов процессов (разделенные запятыми значения).

-t <tid>, —tid=<tid>

События профиля для имеющихся идентификаторов потоков (разделенные запятыми значения).

-u, —uid=

Запись событий в потоках, принадлежащих uid (имя или значение).

-r <priority>, —realtime=<priority>

Сбор данных с указанным приоритетом RT SCHED_FIFO.

—sym-annotate=<symbol>

Аннотирование этого символа.

-K, —hide_kernel_symbols

Сокрытие символов ядра.

-U, —hide_user_symbols

Сокрытие пользовательских символов.

—demangle-kernel

Разбирать символы ядра.

-D, —dump-symtab

Дамп таблицы символов, используемой для профилирования.

-v, —verbose

Задает подробный вывод (ошибки открытия счетчиков и т. п.).

-z, —zero

Задает сброс истории при обновлении экрана.

-s, —sort

Задает сортировку по ключу — pid, comm, dso⁷, symbol, parent, srcline, weight, local_weight, abort, in_tx, transaction, overhead, sample, period (см. report).

—fields=

Задает поля вывода. Множество полей можно указать в формате CSV. Доступны поля overhead, overhead_sys, overhead_us, overhead_children, sample и period. Можно указать также ключи сортировки. По умолчанию, ключи сортировки, не заданные в поле —fields, будут добавляться автоматически.

-n, —show-nr-samples

Задает вывод столбца с числом выборок.

—show-total-period

Задает вывод столбца с суммой периодов.

—dsos

Задает рассмотрение лишь символов указанных объектов dso, влияя на % в столбце overhead (см. —percentage).

—comms

Задает рассмотрение лишь символов в указанных столбцах, влияя на % в столбце overhead (см. —percentage).

—symbols

Задает рассмотрение лишь указанных символов, влияя на % в столбце overhead (см. —percentage).

-M, —disassembler-style=

Задает стиль дизассемблирования для objdump.

—source

Задает чередование исходного кода с ассемблерным. По умолчанию включена и отключается опцией —no-source.

—asm-raw

Показывает необработанное кодирование ассемблерных инструкций.

-g

Включает запись графа вызовов (stack chain/backtrace).

—call-graph [mode,type,min[,limit],order[,key][,branch]]

Устанавливает и включает запись графа вызовов, подразумевая опцию -g (см. —call-graph в record и report).

—children

Накапливает цепочку вызовов дочернего процесса к родительской записи, чтобы их можно было сопоставить в выводе. Вывод будет включать столбец Children и сортироваться по его значению (нужна опция -g или —call-graph). Подробности приведены в разделе Расчет издержек. По умолчанию опция включена и отключается —no-children.

—max-stack

Устанавливает предел глубины стека при разборе цепочки вызовов, устанавливая компромисс между потерей деталей и скоростью обработки, особенно для задач с большой глубиной стека вызовов. По умолчанию используется значение 127 или содержимое файла /proc/sys/kernel/perf_event_max_stack, если он имеется.

—ignore-callees=<regex>

Задает игнорирование вызывающих функции, указанные регулярным выражением regex. Это оказывает влияние на сбор статистики о вызывающих такие функции, указывая их лишь один раз в дереве графа вызовов.

—percent-limit

Отключает вывод записей с издержками ниже указанных (по умолчанию 0).

—percentage relative|absolute

Определяет вывод процента издержек отфильтрованных записей. Фильтры могут применяться с помощью опций —comms, —dsos и,или —symbols, а также операций Zoom в TUI⁸ (thread, dso и т. п.).

Относительный вариант (relative) означает, что издержки рассчитываются только для отфильтрованных записей, поэтому сумма показанных значений будет составлять 100%. При абсолютном варианте (absolute) применяется исходное значение до и после применения фильтра.

-w, —column-widths=<width[,width…]>

Задает ширину каждой колонки для удобочитаемости. 0 отменяет ограничение и используется по умолчанию.

—proc-map-timeout

Обработка уже имеющихся потоков /proc/XXX/mmap может занять продолжительное время и для таких случаев нужно установить время ожидания. По умолчанию тайм-аут составляет 500 мсек.

-b, —branch-any

Включает выборку из стека ветвления. Выбираться могут любые типы ветвей. Эта опция является сокращением для —branch-filter any (см. —branch-filter).

-j, —branch-filter

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

Опция требует указания хотя бы одного из типов any, any_call, any_ret, ind_call, cond. Уровни привилегий можно опускать и в этом случае к фильтру ветвления будет применяться уровень привилегий связанного события. Уровни привилегий как ядра (k), так и гипервизора (hv) зависят от разрешений. При выборке множества событий выборка стека ветвления включается для всех отбираемых событий. Тип отбираемого ветвления одинаков для всех событий. Разные фильтры должны указываться в виде разделенного запятыми списка —branch-filter any_ret,u,k. Отметим, что на некоторых процессорах эта опция не поддерживается.

—raw-trace

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

—hierarchy

Включает иерархический вывод.

—overwrite

Включает использование самых свежих записей. Это помогает в машинах с большим числом ядер (таких как Knights Landing/Mill), но по умолчанию отключено, поскольку используемая этим методом пауза ведет к потере событий метаданных (таких как PERF_RECORD_MMAP), что мешает perf top преобразовать выборки и ведет к появлению множества нераспознанных выборок в пользовательском интерфейсе. Эту опции следует включать на упомянутых машинах при профилировании работы, не создающей краткосрочных потоков и/или не использующих большого числа выполняемых операций mmap. Планируется работа по решению проблемы с паузой, но пока опция отключена по умолчанию.

—force

Отключает проверку владения.

—num-thread-synthesize

Задает число потоков, запускаемых при синтезе событий для имеющихся процессов. По умолчанию число потоков совпадает с числом активных CPU.

Клавиши интерактивного управления

[d]

Выводит интервал обновления.

[e]

Число выводимых записей.

[E]

Отображаемое событие при активности нескольких счетчиков.

[f]

Фильтр отображения профиля (>= счетчика обращений).

[F]

Фильтр вывода аннотаций (>= % от общего).

[s]

Аннотировать символы.

[S]

Прекратить аннотирование с возвратом вывода полного профиля.

[K]

Скрыть символы ядра.

[U]

Скрыть пользовательские символы.

[z]

Переключить режим обновления счетчиков при обновлении.

[qQ]

Завершение работы.

Нажатие любой другой клавиши приведет к выводу меню для выбора варианта.

Расчет издержек

Издержки (overhead) могут выводиться в столбцах Children и Self, когда perf собирает цепочки вызовов. Собственные (self) издержки рассчитываются просто путем сложения всех значений периодов для записи — обычно это функция (символ). Это будет значение, которое традиционно показывает perf и сумма всех собственных издержек будет составлять 100%.

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

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

Рассмотрим пример с тремя функциями.

          void foo(void) { 
              /* do something */ 
          } 

          void bar(void) {
              /* do something */ 
              foo(); 
          } 

          int main(void) { 
              bar() 
              return 0; 
          } 
В этом случае foo является потомком bar, а bar - прямым потомком main, поэтому foo является также потомком main. Иными словами, main является предком foo и bar, а bar - предком foo.

Предположим, что все выборки выполняются только в foo и bar. При записи с помощью цепочек вызовов вывод perf будет иметь вид

          Overhead  Symbol 
          ........  ..................... 
            60.00%  foo 
                    | 
                    --- foo 
                        bar 
                        main 
                        __libc_start_main 

            40.00%  bar 
                    | 
                    --- bar 
                        main 
                        __libc_start_main 
При включенной опции --children значения собственных издержек дочерних функций (foo и bar) добавляются к родительским издержкам и вывод будет иметь вид
          Children      Self  Symbol 
          ........  ........  .................... 
           100.00%     0.00%  __libc_start_main 
                    | 
                    --- __libc_start_main 

           100.00%     0.00%  main 
                    | 
                    --- main 
                        __libc_start_main 

           100.00%    40.00%  bar 
                    | 
                    --- bar 
                        main 
                        __libc_start_main 

            60.00%    60.00%  foo 
                    | 
                    --- foo 
                        bar 
                        main 
                        __libc_start_main 
Видно, что собственные издержки foo (60%) добавлены к дочерним издержкам bar, main и __libc_start_main. Аналогично, собственные задержки bar (40%) добавлены к дочерним издержкам main и __libc_start_main.

Таким образом, __libc_start_main и main показаны первыми, поскольку они имеют одинаковые (100%) издержки потомков (даже при нулевых собственных издержках) и являются родителями foo и bar.

Начиная с версии 3.16, дочерние издержки выводятся по умолчанию и применяются для сортировки вывода. Отключить издержки потомков можно с помощью опции —no-children в командной строке, а также добавлением report.children = false или top.children = false в конфигурационный файл perf.

record

Выполняет пользовательскую команду и записывает профиль работы в файл perf.data. Полученный файл можно затем использовать для подготовки отчета с помощью perf report.

Синтаксис

perf record [-e <EVENT> | --event=EVENT] [-a] <command> 
perf record [-e <EVENT> | --event=EVENT] [-a] - <command> [<options>]

Опции

<command>…

Любая команда, которую можно выполнить в командном процессоре.

-e, —event=

Задает событие PMU, которое может быть указано перечисленными ниже способами.

Символическое имя события (perf list позволяет увидеть список всех событий).
Необработанное событие PMU (eventsel+umask) в форме rNNN, где NNN является шестнадцатеричным дескриптором события.
Символически сформированное имя вида pmu/param1=0x3,param2/, где param1 и param2 определены как форматы для PMU в файлах /sys/bus/event_source/devices/<pmu>/format/*.
Символически сформированное имя вида pmu/config=M,config1=N,config2=K/, где M, N, K — числа в десятичном, шестнадцатеричном или восьмеричном формате. Приемлемые значения параметров config, config1 и config2 определяются записями в файлах /sys/bus/event_source/devices/<pmu>/format/*,
Имеются также параметры, не определенные в …/<pmu>/format/*, которые могут применяться взамен принятых по умолчанию значений для каждого событий. Ниже перечислены некоторые из основных параметров.
- period — задает период выборки для события.
- freq — задает частоту выборки для события.
- time — включает (1) и отключает (0) выборку времени (по умолчанию включена).
- call-graph — включает и отключает граф вызовов. Приемлемы строки fp для режима FP, dwarf для режима DWARF⁹, lbr для режима LBR¹⁰ и no для отключения графа вызовов.
- stack-size задает размер пользовательского стека для режима DWARF.
- name — задает определенное пользователем имя события. Можно использовать одинарные кавычки (‘) для корректного разбора строки командным процессором. Например, name=\’CPU_CLK_UNHALTED.THREAD:cmask=0x1\’.
Дополнительная информация представлена в описании команды perf list.

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

В файлах …/<pmu>/format/* не определены также параметры конфигурации конкретных драйверов PMU. Параметры с префиксом @ не интерпретируются в пользовательском пространстве и напрямую передаются драйверу PMU. Например,
```
perf record -e some_event/@cfg1,@cfg2=config/ ...
```
будет смотреть cfg1 и cfg2=config, переданные драйверу PMU, связанному с событием, для дальнейшей обработки. На параметры конфигурации ограничений не налагается, поскольку они семантически понятны и поддерживаются драйвером PMU.
События аппаратных точек прерывания в форме \mem:addr[/len][:access], где addr указывает адрес в памяти, где требуется остановка. Параметр access указывает тип доступа к памяти (чтение, запись, выполнение) и может передаваться в форме \mem:addr[:[r][w][x]]. Параметр len указывает диапазон — число байтов, начиная с addr, которые будет охватывать точка прерывания. Если вы хотите профилировать чтение и запись в 0x1000, просто укажите mem:0x1000:rw. Для профилирования записи в [0x1000~1008) следует указать mem:0x1000/8:w.
Исходный файл BPF¹¹ (например, на языке c) или скомпилированный объектный файл (.o) для выбора одного или множества событий BPF. Программа BPF может привязываться к разным событиям perf по именам разделов ELF.При обработке файла .c программа perf будет искать установленную LLVM для компиляции объектного файла. Можно передать необязательные опции clang с помощью опции командной строки —clang-opt. Например,
```
perf record --clang-opt "-DLINUX_VERSION_CODE=0x50000" -e tests/bpf-script-example.c
```
Отметим, что опция —clang-opt должна размещаться до опции —event/-e.
Группа событий, помещенных в фигурные скобки «{event1,event2,…}». События разделяются запятыми, а группу следует помещать в кавычки для предотвращения разбора командным процессором. Может потребоваться использование опции —group в команде perf report для совместного просмотра групповых событий.

—filter=<filter>

Фильтр событий. Эту опцию следует указывать после селектора событий (-e), который указывает событие точки трассировки или аппаратную трассировку PMU (например, Intel PT или CoreSight).

Фильтры точек трассировки.В этом случае опции —filter объединяются с помощью символов &&.
Фильтры адресовPMU аппаратной трассировки анонсирует свою возможность доступа к фильтрам адресов путем указания отличного от 0 значения в файле /sys/bus/event_source/devices/<pmu>/nr_addr_filters.Фильтры адресов имеют формат
```
filter|start|stop|tracestop <start> [/ <size>] [@<file name>]
```
- filter — указывает область трассировки;
- start — указывает адрес, где начинается трассировка;
- stop — указывает адрес, где останавливается трассировка;
- tracestop — указывает область, где останавливается трассировка.
Параметр <file name> указывает имя объектного файла, <start> — смещение в коде для трассировки, <size> — размер трассируемой области. Фильтры start и stop не обязаны задавать <size>.

Если объектный файл не задан, предполагается ядро и в этом случае стартовым адресом должен быть текущий адрес ядра в памяти.

Параметр <start> можно также указать именем символа. Если это имя не уникально, можно снять неоднозначность указанием #n, где n является порядковым номером символа в упорядоченном по адресам списке. Параметры #0, #g или #G позволяют выбирать только глобальные символы. Параметр <size> можно также задать именем символа и в этом случае размер определяется по завершению символа. Для фильтров filter и tracestop при отсутствии параметра <size> и указании параметра <start> символом размер определяется по завершению этого символа.

Если параметр <size> не задан, а в качестве <start> указано *, начало и размер рассчитываются по первому и последнему символу, т. е. трассируется весь файл.

Если представлены имена символов или *, перед ними и после них должны быть пробельные символы.

Передаваемый ядру фильтр не обязательно совпадает с введенным. Для просмотра передаваемого фильтра используйте опцию -v.

Ядро может оказаться не способным настроить область трассировки, если она не находится в одном отображении. Можно проверить события MMAP (или /proc/<pid>/maps) для контроля этой возможности.

Фильтры могут разделяться пробелами или запятыми.

—exclude-perf

Не записывать события, вызванные самой программой perf. Опцию следует указывать после селектора событий (-e), который выбирает точки трассировки. Она дополняет фильтры выражением common_pid != $PERFPID. При наличии другой опции —filter новый фильтр будет объединяться с ней операцией И (&&).

-a, —all-cpus

Сбор данных в масштабе системы со всех CPU (принято по умолчанию, если цель не задана).

-p, —pid=

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

-t, —tid=

Запись событий для существующих потоков, заданных списком разделенных запятыми идентификаторов. Эта опция также запрещает наследование по умолчанию (включается опцией —inherit).

-u, —uid=

Записывает события в потоках, принадлежащих uid (имя или номер).

-r, —realtime=

Собирает данные с указанным приоритетом RT SCHED_FIFO.

—no-buffering

Собирает данные без буферизации.

-c, —count=

Период событий для выборки.

-o, —output=

Имя выходного файла.

-i, —no-inherit

Дочерние задачи не наследуют счетчики.

-F, —freq=

Профилирование с указанной частотой. Для использования максимально доступной частоты служит значение max (значение переменной kernel.perf_event_max_sample_rate). Будет снижать частоту выборки до максимальной частоты, разрешенной в данный момент (см. —strict-freq).

—strict-freq

Ведет к отказу, если заданная частота не может применяться.

-m, —mmap-pages=

Число страниц данных mmap (должно быть степенью 2) или размер с суффиксом единицы (B/K/M/G). Размер округляется до ближайшей степени 2. Можно также указать через запятую число страниц mmap для области трассировки AUX.

—group

Помещать все события в одну группу. Предшествует опции —event и сохранена для совместимости с прежними версиями.

-g

Включает запись графа вызовов.

—call-graph

Организует и включает запись графа вызовов, подразумевая опцию -g. Можно выбрать режим fp (применяется по умолчанию), dwarf (DWARF CFI¹²) или lbr в качестве метода сбора информации для графа вызовов.

В некоторый системах, где при сборке применяется команда gcc —fomit-frame-pointer, метод fp, будет давать «фиктивный» граф вызовов и следует применять метод dwarf, если это возможно (модули perf собраны с библиотекой libunwind или libdw). Для метода lbr не требуются какие-либо опции компилятора и он будет строить граф по аппаратным регистрам LBR. Основным ограничением этого режима является его доступность лишь на новых платформах Intel, таких как Haswell. Он может давать лишь цепочку пользовательских вызовов и не работает одновременно в выборкой стека ветвлений.

При использовании метода dwarf программа perf записывает также дамп (пользовательского) стека при выборках. По умолчанию размер дампа стека составляет 8192 байта. Можно изменить размер, указав новое значение через запятую, например, —call-graph dwarf,4096.

-q, —quiet

Отключает вывод сообщений, что может быть полезно при использовании сценариев.

-v, —verbose

Задает более подробный вывод (ошибки открытия счетчиков и т. п.).

-s, —stat

Задает запись счетчиков событий по потокам (thread). Для просмотра значений применяется команда perf report -T.

-d, —data

Запись виртуальных адресов выборок.

—phys-data

Запись физических адресов выборки.

-T, —timestamp

Запись временных меток выборки. Для просмотра меток можно использовать perf report -D.

-P, —period

Запись периода выборки.

—sample-cpu

Запись CPU для выборки.

-n, —no-samples

Отказ от выборки.

-R, —raw-samples

Собирать необработанные записи выборки из всех открытых счетчиков принято по умолчанию для счетчиков точек трассировки).

-C, —cpu

Делать выборки лишь для заданных списком CPU. Процессоры указываются через запятую (0,1) или диапазоном (0-2) без пробелов. В режиме выборки по потокам при включенном наследовании принято по умолчанию), выборка выполняется лишь при выполнении потоков на указанных CPU. По умолчанию отслеживаются все процессоры.

-B, —no-buildid

Не сохранять идентификаторы сборки двоичных файлов в perf.data. В результате пропускается пост-обработка после записи, которая иногда может быть долгой, поскольку требуется обрабатывать все события в поиске записей mmap. Недостатком этого подхода является возможность ошибок преобразования символов, если двоичные файлы задачи, использованной при записи, были обновлены или собраны заново, поскольку они доступны в этом случае лишь по именам. Можно также установить для конфигурационной переменной record.build-id значение skip для постоянного отказа от записи идентификаторов сборки.

-N, —no-buildid-cache

Не обновлять кэш идентификаторов сборки. Это снижает издержки обработки в некоторых ситуациях, когда достаточно информации в файле perf.data (включает buildid). Можно также отказаться от кэширования постоянно, указав в конфигурационном файле для переменной record.build-id значение no-cache.

-G name,…, —cgroup name,…

Задает отслеживание лишь контейнера (cgroup) с именем name. Опция доступна только в режиме отслеживания по процессорам (per-cpu). Должна быть смонтирована файловая система cgroup. Все потоки, относящиеся к контейнеру name, отслеживаются при работе на контролируемых CPU. Можно указать несколько контейнеров cgroup, каждый из которых будет применяться к соответствующему событию (первое событие для первого контейнера cgroup, второе — для второго и т. д.). Можно указать пустой контейнер cgroup (отслеживать всегда), например, -G foo,,bar. Контейнеры cgroup должны иметь соответствующие события, т. е. всегда указывать на событие, указанное ранее в командной строке. Если нужно отслеживать несколько событий в одном контейнере cgroup, можно указать -e e1 -e e2 -G foo,foo или просто -e e1 -e e2 -G foo.

Если нужно отслеживать, например, циклы для cgroup в масштабе всей системы, можно воспользоваться командой perf stat -e cycles -G cgroup_name -a -e cycles.

-b, —branch-any

Включает выборку стека ветвления. Могут выбираться любые типы ветвлений. Эта опция является сокращением для —branch-filter any (см. —branch-filter).

-j, —branch-filter

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

any — все типы ветвлений;
any_call — вызов любой функции или системный вызов;
any_ret — возврат из любой функции или системного вызова;
ind_call — любое непрямое ветвление;
call — прямые вызовы включая длинные (в ядро или из него);
u — только ветвления на пользовательский уровень;
k — только ветвления на уровень ядра;
hv — только ветвления на уровень гипервизора;
in_tx — только ветвления в аппаратные транзакции;
no_tx — кроме ветвлений в аппаратные транзакции;
abort_tx — только ветвления для прерываний аппаратных транзакций;
cond — условные ветвления;
save_type — сохранять тип ветвления при выборке, если двоичный код позднее не доступен.

Опция требует хотя бы один тип ветвления из any, any_call, any_ret, ind_call, cond. Уровни привилегий можно опускать и в этом случае для фильтра ветвления используется уровень привилегий связанных событий. Использоваться могут уровни привилегий ядра (k) и гипервизора (hv). При выборке множества событий включается выборка стека ветвления для всех отслеживаемых событий. Тип выбираемого ветвления совпадает для всех событий. Разные фильтры должны указываться через запятые, например, —branch-filter any_ret,u,k. Фильтрация ветвления доступна не для всех процессоров.

—weight

Включает взвешенную выборку. Записывается дополнительно вес каждой выборки, который можно просматривать с помощью ключей сортировки weight и local_weight. В настоящее время это работает для событий прерывания TSX¹³ и некоторых событий памяти в режиме precise на современных Intel CPU.

—namespaces

Запись событий типа PERF_RECORD_NAMESPACES.

—transaction

Запись флагов транзакции для связанных с транзакциями событий.

—per-thread

Использование mmap на уровне потока (thread). По умолчанию mmap создаются на уровне процессора, но данная опция позволяет переопределить это поведение. Побочным эффектом является запрет наследования. Опция —per-thread игнорируется с выдачей предупреждения при наличии в команде опции -a или -C.

-D, —delay=

Задает задержку начала измерений после запуска программы (в миллисекундах). Это полезно для исключения измерений на стартовой фазе программы, когда ее поведение отличается.

-I, —intr-regs

Фиксация состояния машины (регистров) в момент прерывания, т. е. при переполнении счетчика для каждой выборки. Набор регистров зависит от архитектуры. Опция по умолчанию отключена. Можно указать регистры для выборки по их символьным именами, например, для x86 — ax, si. Для получения списка доступных регистров используется —intr-regs=\?. Регистры указываются через запятые, например, —intr-regs=ax,bx.

—user-regs

Похожа на -I, но фиксирует в момент выборки пользовательские регистры. Список регистров можно получить с помощью —user-regs=\?.

—running-time

Запись времени работы и активности для чтения событий (:S).

-k, —clockid

Задает идентификатор часов для использования в полях времени различных записей perf_event_type (см. clock_gettime()). Поддерживаются, в частности, часы CLOCK_MONOTONIC и CLOCK_MONOTONIC_RAW, а некоторые события могут использовать CLOCK_BOOTTIME, CLOCK_REALTIME и CLOCK_TAI.

-S, —snapshot

Выбирает режим Snapshot с областью AUX. Опция действует только с событиями трассировки области AUX. Дополнительно можно указать число байтов на снимок. В режиме Snapshot данные трассировки фиксируются лишь при получении сигнала SIGUSR2.

—proc-map-timeout

Обработка имеющихся потоков /proc/XXX/mmap может занять много времени по причине очень больших файлов. В таких случаях нужно задать тайм-аут, который устанавливается это опцией (по умолчанию 500 мсек).

—switch-events

Запись событий переключения контекста (PERF_RECORD_SWITCH или PERF_RECORD_SWITCH_CPU_WIDE).

—clang-path=PATH

Путь к библиотеке clang для использования при компиляции сценариев BPF (включается при поддержке BPF).

—clang-opt=OPTIONS

Опции, передаваемые clang при компиляции сценариев BPF (включается при поддержке BPF).

—vmlinux=PATH

Путь к файлу vmlinux с отладочной информацией (включается при поддержке BPF).

—buildid-all

Запись идентификаторов сборки для всех DSO, независимо от их участия.

—aio[=n]

Использовать <n> блоков управления в асинхронном режиме записи трассировки (Posix AIO) (по умолчанию 1, максимально 4). Асинхронный режим поддерживается лишь при компоновке perf с библиотекой libc, обеспечивающей реализацию Posix AIO API.

—affinity=mode

Задает маску сходства потоков чтения трассировки в соответствии с политикой, заданной значением mode. Режим node (узел) задает маску сходства по маске узла NUMA процессора, обрабатывающего буфер mmap, cpu задает маску сходства по процессору, обрабатывающему буфер mmap.

—mmap-flush=number

Задает минимальное число байтов, извлекаемых из страниц данных mmap и обрабатываемых для вывода. Можно использовать суффиксы B/K/M/G (байты, кило-, мега- и гигабайты).

Максимально разрешенное значение составляет четверть от размера страниц mmap.

По умолчанию используется значение 1 байт, которое указывает, что при каждом обнаружении потоком записи вывода новых данных в буфере mmap эти данные извлекаются (возможно со сжатием при -z) и записываются в файл perf.data или конвейер.

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

В некоторых случаях снижение числа системных вызовов записи вывода за счет большего размера блоков может уменьшать время выполнения и издержки профилирования.

-z, —compression-level[=n]

Задает сжатие трассировки с использованием уровня n (по умолчанию 1 — максимальная скорость, для максимального сжатия используется уровень 22).

—all-kernel

Задает для всех используемых событий работу в пространстве ядра.

—all-user

Задает для всех используемых событий работу в пользовательском пространстве.

—timestamp-filename

Добавляет временную метку к выводимому имени файла.

—timestamp-boundary

Записывает границы временных меток (время первой и последней выборки).

—switch-output[=mode]

Задает создание множества файлов perf.data с временной меткой в качестве префикса, переходя к новому файлу в соответствии с режимом. В режиме signal (используется по умолчанию) переход происходит по получению SIGUSR2, в режиме <size> — по достижению заданного размера¹⁴ (число с суффиксом B/K/M/G), <time> — по истечении заданного времени (число с суффиксом s/m/h/d).

Возможным вариантом использования является «нарезка» файлов perf.data для последующей обработки (возможно в perf script) с возможностью отказа от сохранения следующего файла.

Предполагаются опции —timestamp-filename, —no-buildid и —no-buildid-cache. Две последних опции служат для снижения издержек, связанных с переходом к другому файлу. Их можно выключить с помощью

    --switch-output --no-no-buildid --no-no-buildid-cache

—switch-max-files=N

При ротации perf.data с опцией —switch-output задает сохранение только N файлов.

—dry-run

Разбор опций и завершение работы. Служит для обнаружения ошибок в командах. Команда perf record —dry-run -e может применяться для компиляции сценариев BPF, если в конфигурационном файле указано значение true для переменной llvm.dump-obj.

—tail-synthesize

Вместо сбора неотбираемых событий (например, fork, comm, mmap) в начале записи задает их сбор при завершении выходного файла. Эти события отражают состояние системы при завершении записи.

—overwrite

Заставляет использовать перезаписываемый кольцевой буфер для всех событий. При заполнении буфера продолжается запись в начало и первые события не попадут в файл perf.data.

При использовании опций —overwrite и —switch-output программа perf записывает и отбрасывает события до получения сигнала, означающего необычное событие, требующее создания моментального снимка (snapshot) самых последних событий, которые в этот момент находятся в кольцевом буфере.

Атрибут overwrite можно установить или сбросить с помощью конфигурации. Например, cycles/overwrite/ и instructions/no-overwrite/.

Предполагается опция —tail-synthesize.

report

Считывает файл данных perf.data, созданный командой perf record , и выводит профиль производительности, построенный по собранным ранее данным.

Синтаксис

perf report [-i <file> | --input=file]

Опции

-i, —input=

Имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-v, —verbose

Задает подробный вывод (адреса символов и т. п.)

-q, —quiet

Отменяет вывод сообщения, отменяя опцию -v.

-n, —show-nr-samples

Выводит число выборок для каждого символа.

—show-cpu-utilization

Показывает загрузку процессора для разных режимов.

-T, —threads

Показывает счетчики событий для потоков (thread). Фал данных для этого следует записывать с опцией -s.

-c, —comms=

Задает учет символов лишь в указанных столбцах. Можно использовать файл CSV, заданный параметром file://filename. Эта опция будет влиять на столбец overhead (см. —percentage).

—pid=

Задает вывод событий лишь для указанного идентификатора процесса (список разделенных запятыми значений).

—tid=

Задает вывод событий лишь для указанного идентификатора потока (список разделенных запятыми значений).

-d, —dsos=

Задает учет лишь символов указанных dso. Можно использовать файл CSV, заданный параметром file://filename. Эта опция будет влиять на столбец overhead (см. —percentage).

-S, —symbols=

Задает учет лишь указанных символов. Можно использовать файл CSV, заданный параметром file://filename. Эта опция будет влиять на столбец overhead (см. —percentage).

—symbol-filter=

Задает вывод лишь символов, которые соответствуют (частично) данному фильтру.

-U, —hide-unresolved

Задает вывод лишь записей, преобразованных в символы.

-s, —sort=

Задает сортировку гистограммы по указанным ключам. Для задания множества ключей можно использовать формат CSV. Доступна сортировка по ключам pid, comm, dso, symbol, parent, cpu, socket, srcline, weight, local_weight, cgroup_id.

Значения ключей описаны ниже.

comm — команда (имя) задачи, которую можно прочитать в /proc/<pid>/comm.
pid — команда и идентификатор потока для задачи.
dso — имя библиотеки или модуля, выполняемого в момент выборки.
dso_size — размер библиотеки или модуля, выполняемого в момент выборки.
symbol — имя функции, выполняемой в момент выборки.
symbol_size — размер функции, выполняемой в момент выборки.
parent — имя функции, соответствующей регулярному выражению родительского фильтра. Не соответствующие записи выводятся как [other].
cpu — номер cpu задачи, выполнявшейся в момент выборки.
socket — номер процессорного сокета задачи, выполнявшейся в момент выборки.
srcline — имя файла номер строки, выполнявшейся в момент выборки. Должна быть предоставлена отладочная информация DWARF.
srcfile — имя файла совпадает с именем файла исходного кода. Требуются данные DWARF.
weight — связанный с событием (глобальный) вес, например, задержка памяти или стоимость прерывания транзакции.
local_weight — локальный вариант указанного выше веса.
cgroup_id — идентификатор, выведенный из значений пространства имен cgroup для устройства и inode.
transaction — флаги прерывания транзакции.
overhead — процент издержек для выборки.
overhead_sys — процент издержек для выборки в системном режиме.
overhead_us — процент издержек для выборки в пользовательском режиме.
overhead_guest_sys — процент издержек для выборки в системном режиме на гостевой машине.
overhead_guest_us — процент издержек для выборки в пользовательском режиме на гостевой машине.
sample — номер выборки.
period — необработанное значение счетчика событий для выборки.
time — разделяет выборки по временным меткам с разрешением, заданным параметром —time-quantum (по умолчанию 100 мсек). Указывается с издержками или перед ними.

По умолчанию применяются ключи comm, dso и symbol (т. е. —sort comm,dso,symbol). Если задана опция —branch-stack, доступны также перечисленные ниже ключи.

dso_from — имя библиотеки или модуля, где произошло ветвление.
dso_to — имя библиотеки или модуля, куда было выполнено ветвление.
symbol_from — имя функции, где произошло ветвление.
symbol_to — имя функции, куда было выполнено ветвление.
srcline_from — файл исходного кода и строка, где произошло ветвление.
srcline_to — файл исходного кода и строка, куда было выполнено ветвление.
mispredict — N для предсказанного ветвления, Y — для ошибочно предсказанного.
in_tx — ветвление в транзакции TSX¹⁵.
abort — прерывание транзакции TSX.
cycles — циклы в базовом блоке.

Принятые по умолчанию ключи сортировки заменяются на comm, dso_from, symbol_from, dso_to и symbol_to (см. —branch-stack).

Когда заданы ключи сортировки, столбцы IPC¹⁶ и IPC Coverage включаются автоматически. IPC показывает среднее значение на функцию, а IPC coverage — процент инструкций, которые отобраны в этой функции. Низкое значение говорит о возможном узком месте при выполнении функции, например, при доступе к памяти. Если функция имеет высокую загрузку (overhead) и малое значение IPC, следует дополнительно проанализировать ее для оптимизации.

При использовании опции —mem-mode доступны также перечисленные ниже ключи (несовместимо с —branch-stack).

symbol_daddr — имя символа данных, выполняемого в момент выборки.
dso_daddr — имя библиотеки или модуля, содержащего данные, выполняемые в момент выборки.
locked — была ли шина заблокирована в момент выборки.
tlb — тип tlb для доступа к данным в момент выборки.
mem — тип доступа к памяти для данных в момент выборки.
snoop — тип snoop (если есть) для данных в момент выборки.
dcacheline — адрес данных cacheline в момент выборки.
phys_daddr — физический адрес данных, выполняемых в момент выборки.

Принятые по умолчанию ключи сортировки заменяются на local_weight, mem, sym, dso, symbol_daddr, dso_daddr, snoop, tlb, locked (см. —mem-mode).

Если файл данных имеет события точек трассировки, доступны также приведенные ниже (динамические) ключи сортировки.

trace — вывод трассировки в один столбец.
trace_fields — вывод трассировки в отдельных столбцах.
[<event>.]<field>[/raw] — необязательное имя события и имя указанного поля

Последняя форма включает имена события и поля. Если имя события опущено, выполняется поиск всех событий, соответствующий имени поля. Совпадающее поле будет выводиться только для событий, имеющих это поле. Для имен событий поддерживается сопоставление подстроки, поэтому пользователь не обязан каждый раз полностью указывать подсистему и имя события. Например, sched:sched_switch можно сократить для switch, если не возникает неоднозначности. Событие также можно указать индексом (отсчет с 1) с префиксом % (%1 для первого события, %2 для второго и т. д.).

Имя поля может иметь суффикс /raw, который отключает «красивую» печать и имя поля выводится подобно шестнадцатеричным числам. Опция —raw-trace будет давать одинаковый эффект для всех динамических ключей сортировки.

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

-F, —fields=

Задает поля вывода, позволяя указать множество ключей в формате CSV. Доступны поля overhead, overhead_sys, overhead_us, overhead_children, sample и period. Можно также указывать любые ключи сортировки. По умолчанию ключи сортировки, не заданные в -F, добавляются автоматически. Если ключи начинаются с префикса +, указанные поля будут добавлены после используемых по умолчанию полей. Например, perf report -F +period,sample.

-p, —parent=<regex>

Регулярное выражение для идентификации родителя, каковым является вызвавший эту функцию. Поиск родителя выполняется в цепочке вызовов, поэтому нужно записать эту информацию. Шаблон поиска использует расширенный формат регулярных выражений. По умолчанию используется ^sys_|^do_page_fault (см. —sort parent).

-x, —exclude-other

Задает вывод лишь записей для соответствующего родителя.

-w, —column-widths=<width[,width…]>

Задает ширину каждого столбца в выводе для удобочитаемости. Используемое по умолчанию значение 0 задает неограниченную ширину.

-t, —field-separator=

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

-D, —dump-raw-trace

Дамп необработанной трассировки в формате ASCII.

-g, —call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>

Отображение цепочек вызовов с использованием print_type, threshold, print_limit, order, sort_key, (необязательно) branch и value. Порядок не фиксирован и параметры можно размещать произвольно. Исключением является лишь размещение print_limit после threshold.

Параметр print_type может принимать любое из приведенных ниже значений.

flat — один столбец, линейное отображение всех цепочек вызовов.
graph — дерево графа с выводом абсолютных значений издержек (принято по умолчанию).
fractal — похоже на graph, но выводятся относительные значения. Каждая ветвь дерева считается новым объектом профилирования.
folded — цепочки вызовов отображаются в строке с разделением точкой с запятой (;).
none — цепочки вызовов не отображаются.

Параметр threshold задает минимальное процентное значение, которое включается в вывод графа вызовов (по умолчанию 0,5 %).

Параметр print_limit применяется лишь для интерфейса stdio и ограничивает число записей вызовов в одной записи гистограммы. Отметим, что его нужно указывать после параметра threshold (не обязательно сразу). По умолчанию ограничений не задано (0).

Параметр order может принимать одно из значений:

callee — граф вызовов по вызываемым;
caller — обращенный граф вызовов по вызывающим.

По умолчанию используется caller, если задана опция —children, иначе callee.

Параметр sort_key может принимать значения:

function — по функциям (принято по умолчанию);
address — по индивидуальным адресам кода;
srcline — по файлам исходного кода и номерам строк.

Необязательный параметр branch задает включение информации о ветвлении (если она доступна) в граф вызовов. Обычно удобней для этого использовать опцию —branch-history.

Параметр value может принимать значения:

percent — вывод издержек в процентах (принято по умолчанию);
period — вывод периода события;
count — вывод счетчика события.

—children

Задает накопление дочерних вызовов родительской записи для последующего отображения. Вывод будет включать столбец Children, по которому будет выполняться сортировка данных. Для этого требуется запись цепочек вызовов. Дополнительные сведение приведены в разделе «Расчет издержек». Опция по умолчанию включена, отключить ее можно опцией —no-children.

—max-stack

Задает ограничение глубины стека при разборе цепочки вызовов. Это задает компромисс между объемом информации и скоростью обработки для заданий, имеющих очень большую глубину стека вызовов. Отметим, что при использовании опции —itrace синтезированный размер цепочки вызовов будет переопределять это значение, если оно меньше синтезированного. По умолчанию используется глубина стека 127.

-G, —inverted

Псевдоним для обращенного графа по вызывающим.

—ignore-callees=<regex>

Задает игнорирование вызываемых (callee) для функций, соответствующих регулярному выражению regex. Это влияет на сбор данных о вызывающих для каждой такой функции в дереве графа вызовов.

—pretty=<key>

Задает «красивый» стиль вывода. Ключ может принимать значение normal или raw.

—stdio

Задает использование интерфейса stdio.

—stdio-color

Значения always (всегда), never (никогда) или auto (автоматически) управляют выводом цвета через командную строку в дополнение к параметрам color.ui в конфигурационном файле. Опцию —stdio-color следует всегда использовать для управления цветом при перенаправлении вывода в конвейер или файл. Опция —stdio-color без параметра задает использование цвета всегда.

—tui

Задает использование интерфейса TUI, интегрированного с аннотированием и позволяющего масштабировать (zoom) вывод с просмотром DSO или потоков (thread), а также обеспечивающего другие возможности. Опция —tui требует наличия терминала и при его отсутствии или использовании конвейера с другими командами будет применяться интерфейс stdio.

—gtk

Задает использование интерфейса GTK2.

-k, —vmlinux=<file>

Путь к файлу vmlinux.

—ignore-vmlinux

Задает игнорирование файлов vmlinux.

—kallsyms=<file>

Путь к файлу kallsyms.

-m, —modules

Задает загрузку символов модулей. Важно отметить, что это следует применять с опцией -k и «живым» ядром.

-f, —force

Отключает проверку владения.

—symfs=<directory>

Задает поиск файлов с символами относительно указанного каталога.

-C, —cpu

Задает включение в отчет лишь выборок для указанных списком CPU. Процессоры можно перечислить через запятые (0,1) или указать диапазон (0-2) без пробелов. По умолчанию учитываются все CPU.

-M, —disassembler-style=

Задает стиль дизассемблирования для objdump.

—source

Задает чередование исходного кода с ассемблерным. По умолчанию включено, отключается опцией —no-source.

—asm-raw

Задает вывод необработанного кодирования ассемблерных инструкций.

—show-total-period

Задает вывод столбца с суммой периодов.

-I, —show-info

Задает вывод расширенной информации о файле perf.data. Эти данные могут быть очень велики и занять много места на экране. В настоящее время они включают топологию cpu и numa для хост-системы.

-b, —branch-stack

Использовать для построения гистограммы адреса ветвлений в выборках вместо адресов инструкций. Для создания значимого вывода файл perf.data должен быть записан с использованием опции record -b или perf record —branch-filter xxx, где xxx задает фильтр ветвления. Команда perf report может автоматически определять наличие стеков ветвления в файле perf.data и переключаться в режим просмотра ветвлений, если не задана опция.

—branch-history

Задает добавление адресов ветвлений в выборках к стеку вызовов. Это позволяет увидеть путь, который проходит программа при каждой выборке. Данные должны собираться с использованием опций -b (или -j) и -g.

—objdump=<path>

Путь к двоичному файлу objdump.

—group

Задает совместный вывод информации для группы событий, форсируя групповой вывод, если группы не были определены в файле данных.

—demangle

Переводит имена символов в удобочитаемый формат. Опция включена по умолчанию и отключается с помощью —no-demangle.

—demangle-kernel

Переводит имена символов ядра в удобочитаемый формат (для ядер C++).

—mem-mode

Задает использование адресов данных в выборках в дополнение к адресам инструкций при построении гистограмм. Для создания значимого вывода файл perf.data должен быть записан с помощью команды perf record -d -W и с указанием специального события -e cpu/mem-loads/p или -e cpu/mem-stores/p (см perf mem).

—percent-limit

Отключает вывод записей с издержками ниже заданного порога (по умолчанию 0). Эта опция также устанавливает порог для цепочек вызовов, однако используемое для этого порога значение по умолчанию отличается от значения, применяемого по умолчанию для гистограмм (см. —call-graph).

—percentage

Задает способ отображения процента издержек для отфильтрованных записей. Фильтры можно задать опциями —comms, —dsos, —symbols или операциями Zoom в TUI (thread, dso и т. п.).

Значение relative задает вывод относительно отфильтрованных записей и сумма всегда будет составлять 100%. В случае absolute расчет выполняется относительно исходных значений до и после фильтрации.

—header

Задает вывод заголовка файла perf.data, включающего такую информацию, как имя хоста, версии ОС и perf, данные процессоров и памяти, командная строка perf, список событий и т. п. В настоящее время эта функция поддерживается только для режима вывода —stdio.

—header-only

Задает вывод лишь заголовка perf.data (включает опцию —stdio).

—time

Задает анализ выборок лишь из временного окна <start>,<stop>. Время указывается в формате секунды.микросекунды. Если время начала не указано (т. е. ,x.y), анализ начинается с начала файла. Если время окончания не указано (т. е. x.y,), анализ выполняется до конца файла.

Поддерживается также указание интервалов в процентах — a%/n,b%/m,… или a%-b%,c%-%d,…

Например, для выбора вторых 10% интервала записи можно использовать команду

              perf report --time 10%/2

Для выбора интервала от 0% до 10% служит команда

              perf report --time 0%-10%

Например, для выбора первых и вторых 10% интервала записи можно использовать команду

              perf report --time 10%/1,10%/2

Для выбора интервалов от 0% до 10% и от 30% до 40% служит команда

              perf report --time 0%-10%,30%-40%

—itrace

Задает опции декодирования данных трассировки инструкций:

i синтезировать события инструкций;

b синтезировать события ветвления;

c синтезировать события ветвления (только вызовы);

r синтезировать события ветвления (только возвраты);

x синтезировать события транзакций;

w синтезировать события ptwrite;

p синтезировать события, связанные с питанием;

e синтезировать события, связанные с ошибками;

d создать журнал отладки;

g синтезировать цепочку вызовов (используется с i или x);

l синтезировать записи последнего ветвления (используется с i или x);

s пропустить указанное число записей в начале.

По умолчанию учитываются все события (—itrace=ibxwpe), за исключением perf (—itrace=ce)

В дополнение к этому можно задать интервал учета (по умолчанию 100000, за исключением perf script, где устанавливается 1) в удобных единицах:

i инструкции;

t такты часов;

ms миллисекунды;

us микросекунды;

ns наносекунды (используется по умолчанию).

Можно также указать размер цепочки (по умолчанию 16, максимум 1024) для событий.

Можно указать также число записей последнего ветвления (по умолчанию 64, максимум 1024).

Можно пропустить генерацию событий (инструкции, ветвления, транзакции, ptwrite, питание) в начале. Это удобно для пропуска фазы инициализации. Например, опция

              --itrace=i0nss1000000

обеспечит пропуск первого миллиона инструкций.

Для полного запрета декодирования служит опция —no-itrace.

—full-source-path

Выводит полный путь к файлам исходного кода при выводе номеров строк.

—show-ref-call-graph

При выборке нескольких событий может не требоваться сбор графа вызовов для всех этих событий. Точки выборки обычно расположены близко и достаточно собрать графы вызовов для опорных событий. Поэтому можно использовать модификатор событий call-graph=no для запрета графа вызовов других событий с целью снижения нагрузки. Эта опция позволяет команде perf report показать опорные графы вызовов без сбора всех графов.

—socket-filter

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

—samples=N

Сохранять N отдельных выборок для каждой записи гистограммы с целью показа контекста в браузере perf report TUI.

—raw-trace

При выводе трассировки событий не применять форматирование вывода и плагины.

—hierarchy

Включает иерархический вывод.

—inline

Если адрес графа вызовов относится к inline-функции, будет выводиться inline-стек, каждая запись которого указывает имя функции или файл и строку. Опция включена по умолчанию, отключается с помощью -no-inline.

—mmaps

Показывает вывод —tasks и информацию mmap в формате, похожем на /proc/<PID>/maps.

Отметим, что сохраняются не все mmap.

—ns

Вывод временных меток в наносекундах.

—stats

Выводит суммарную статистику событий без дополнительной обработки (похоже на завершение вывода по команде perf report -D).

—tasks

Выводит отслеживаемые задачи, сохраненные в файле perf.data, с указанием pid/tid/ppid и командной строки. Вывод организован так, чтобы можно было различить родительские и дочерние задачи.

—percent-type

Задает тип расчета процентов — global-period (за период по всем данным), local-period (за период в области действия функции), global-hits (от числа выбором по всем данным) или local-hits (от числа выбором в области действия функции).

—time-quantum

Задает величину квантования для ключа сортировки по времени (по умолчанию 100 мсек). Можно задать время в секундах, милли-, микро- и наносекундах.

Расчет издержек

См. Расчет издержек в описании top.

annotate

Читает файл perf.data (создается с помощью perf record) и выводит аннотированный код. Если объектный файл включает отладочные символы, ассемблерный код будет сопровождаться исходным кодом. При отсутствии отладочной информации выводится лишь аннотированный ассемблерный код.

Синтаксис

perf annotate [-i <file> | --input=file] [symbol_name]

Опции

-i, —input=<file>

Имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-d, —dsos=<dso[,dso…]>

Задает учет лишь указанных dso.

-s, —symbol=<symbol>

Символ для аннотирования.

-f, —force

Отмена проверки владения.

-v, —verbose

Подробный вывод (адреса символов и т. п.).

-q, —quiet

Не показывать сообщений (отменяет -v).

-n, —show-nr-samples

Показывать число выборок для каждого символа.

-D, —dump-raw-trace

Дамп необработанной трассировки в формате ASCII.

-k, —vmlinux=<file>

Путь к файлу vmlinux.

—ignore-vmlinux

Игнорировать файлы vmlinux.

-m, —modules

Загружать символы модулей (используется только с -k и «живым» ядром).

-l, —print-line

Выводить соответствующие строки исходного кода (может быть медленно).

-P, —full-paths

Не сокращать выводимые пути.

—stdio

Использовать интерфейс stdio.

—stdio2

Использовать неинтерактивный интерфейс stdio2 с форматированием TUI.

—stdio-color=<mode>

Управляет использованием цвета через командную строку — always (всегда), never (никогда) или auto (автоматически) в дополнение к конфигурационному параметру color.ui. Опция —stdio-color позволяет использовать выделение цветом даже при выводе в конвейер или файл. Опция —stdio-color задает использование цвета всегда.

—tui

Использовать интерфейс TUI. Для этой опции нужен терминал. Если терминала нет или команда применяется в конвейере, будет использован интерфейс stdio.

—gtk

Использовать интерфейс GTK.

-C, —cpu=<cpu>

Сообщать только о выборках для указанных CPU. Процессоры можно указать списком через запятые (0,1) или диапазоном (0-2) без пробелов. По умолчанию учитываются все CPU.

—asm-raw

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

—show-total-period

Показывать столбец с суммой периодов.

—source

Чередовать исходный код с ассемблерным. По умолчанию включено, отключается опцией —no-source.

—symfs=<directory>

Поиск файлов с символами относительно указанного каталога.

-M, —disassembler-style=

Устанавливает стиль дизассемблера для objdump.

—objdump=<path>

Путь к библиотеке objdump.

—skip-missing

Пропускать символы, которые не могут быть аннотированы.

—group

Показывать информацию группы событий вместе.

—percent-type

Задает тип расчета процентов — global-period (за период по всем данным), local-period (за период в области действия функции), global-hits (от числа выбором по всем данным) или local-hits ( от числа выбором в области действия функции).

ftrace

Простая оболочка для работы с функциональностью ядра ftrace. В настоящее время поддерживается лишь трассировка одного потока и просто записывается вывод trace_pipe в текстовом формате на stdout.

Синтаксис

perf ftrace <command>

Опции

-t, —tracer=

Используемый трассировщик (function_graph или function).

-v, —verbose=

Уровень детализации.

-p, —pid=

трассировка процессов с указанными идентификаторами (через запятые).

-a, —all-cpus

Сбор данных в масштабе системы. При работе без параметра <command> опция -a включается по умолчанию, в остальных случаях ее нужно задавать явно.

-C, —cpu=

Выполнять трассировку только для указанных CPU. Процессоры можно указать списком через запятые (0,1) или диапазоном (0-2) без пробелов. По умолчанию учитываются все CPU.

-T, —trace-funcs=

Трассировать только указанные параметром функции. Опция может указываться несколько раз и разрешено использование регулярных выражений (glob). Функции передаются set_ftrace_filter в файловой системе tracefs.

-N, —notrace-funcs=

Не трассировать указанные параметром функции. Опция может указываться несколько раз и разрешено использование регулярных выражений (glob). Функции передаются set_ftrace_notrace в файловой системе tracefs.

-G, —graph-funcs=

Задает фильтр графа функций (или шаблон glob). Это полезно лишь для трассировщика function_graph и включает трассировку функций, вызываемых из указанной функции. Опцию можно применять многократно и она передается set_graph_function в файловой системе tracefs.

-g, —nograph-funcs=

Отключает граф указанных функций (или шаблон glob). Это полезно лишь для трассировщика function_graph и выключает трассировку функций, вызываемых из указанной функции. Опцию можно применять многократно и она передается set_graph_notrace в файловой системе tracefs.

-D, —graph-depth=

Задает максимальную глубину для трассировщика function_graph.

trace

Команда выводит события, связанные с целью трассировки. Изначально это вызовы syscall, но могут выводиться и другие события, такие как отказы страниц, время жизни задач, события планировщиков и т. п.

Эта программа может работать «вживую», а не только с файлами perf.data как другие инструменты perf. Файлы для анализа можно создавать с помощью perf record, но сеанс записи должен включать события raw_syscalls (-e raw_syscalls:*). Можно использовать команду perf trace record, которая автоматически включает отслеживание событий raw_syscalls.

Синтаксис

perf trace 
perf trace record

Опции

Ниже перечислены опции команды perf trace, а опции perf trace record можно найти в описании perf record.

-a, —all-cpus

Сбор данных в масштабе системы со всех CPU.

-e, —expr, —event

Список syscall и других событий perf (точки трассировки, события аппаратного кэша и т. п.) для показа. Поддерживаются шаблоны, например, epoll_*, msg и т. п. Полный список событий можно посмотреть по команде perf list. Префикс ! Будет обеспечивать вывод всех syscall, кроме указанных. Для этого символа может потребоваться использование escape.

-D msecs, —delay msecs

Задает ожидание в течение указанного числа миллисекунд перед началом измерения после запуска команды. Это полезно для исключения переходных процессов, происходящих при старте.

-o, —output=

Имя выходного файла.

-p, —pid=

Запись событий имеющихся процессов с указанными через запятую идентификаторами.

-t, —tid=

Запись событий имеющихся потоков с указанными через запятую идентификаторами.

-u, —uid=

Запись событий из потоков, принадлежащих uid (имя или номер).

-G, —cgroup

Запись событий в потоках cgroup.

Группы cgroup для указания можно посмотреть в каталоге /sys/fs/cgroup/perf_event и указать нужную группу (A) в команде

              perf trace -G A -e sched:*switch

Это установит все raw_syscalls:sys_{enter,exit}, pgfault, vfs_getname и т. п., а также _and_ sched:sched_switch в cgroup A, тогда как команда

              perf trace -e sched:*switch -G A

установит только событие sched:sched_switch в группе A, а все другие события (raw_syscalls:sys_{enter,exit} и т. п.) останутся «без» cgroup (в корневой cgroup, на системном уровне и т. п.).

Можно задать несколько cgroup

              perf trace -G A -e sched:*switch -G B

В этом случае syscall будут в группе A, sched:sched_switch — в группе B.

—filter-pids=

Отфильтровывает события указанных через запятую pid и самой трассировки.

-v, —verbose=

Задает уровень детализации вывода.

—no-inherit

Дочерние задачи не наследуют счетчики.

-m, —mmap-pages=

Число страниц данных mmap (должно быть степенью 2) или размер с суффиксом B/K/M/G (округляется до числа страниц, равного ближайшей степени 2).

-C, —cpu

Выполнять трассировку только для указанных CPU. Процессоры можно указать списком через запятые (0,1) или диапазоном (0-2) без пробелов. В режиме по потокам (per-thread) со включенным наследованием (принято по умолчанию), события фиксируются только при выполнении на назначенных CPU. По умолчанию учитываются все CPU.

—duration

Показывать только события с продолжительностью больше N.M мсек.

—sched

Накапливать поток в процессе выполнения и выводить результат в конце сессии.

—failure

Показывать только вызовы syscall с отказами (отличный от 0 код возврата).

-i, —input

Обработка событий из указанного файла perf.data.

-T, —time

Печатать полные временные метки, а не смещение от первой выборки.

—comm

Выводить процессы с идентификаторами. Принято по умолчанию, отключается опцией —no-comm.

-s, —summary

Показывать только сводку syscall с минимальными, максимальными и средними значениями в миллисекундах, а также stddev.

-S, —with-summary

Показывать только сводку syscall со сводкой по потокам с минимальными, максимальными и средними значениями в миллисекундах, а также stddev.

—tool_stats

Показывать статистику инструмента, такую как число обнаружений fd→pathname путем перехвата возвращаемого syscall значения + vfs_getname или путем чтения /proc/pid/fd и т. п.

-f, —force

Выполнять без лишних вопросов.

-F=[all|min|maj], —pf=[all|min|maj]

Трассировка отказов страниц. Можно указать второстепенные, важные или все отказы. По умолчанию важные (maj).

—syscalls

Трассировка системных вызовов. Опция включена по умолчанию, отключается с помощью —no-syscalls.

—call-graph [mode,type,min[,limit],order[,key][,branch]]

Организует и включает запись графа вызовов. Более подробное описание приведено для одноименной опции perf record и perf report. Наиболее полезными для perf trace являются режимы dwarf и lbr, если они поддерживаются.

Использование опции от имени root user увеличивает значение —mmap-pages до 4 максимальных значения для других пользователей (в соответствии с переменной kernel.perf_event_mlock_kb). Это происходит лишь в тех случаях, когда не указана опция —mmap-pages.

—kernel-syscall-graph

Показывать цепочки вызовов ядра на пути выхода syscall.

—max-events=N

Завершать работу после обработки N событий. Отметим, что события типа strace учитываются только на выходе или при прерывании syscall, т. е. в таких случаях эта опция задает число выводимых строк.

—max-stack

Задает глубину стека при анализе цепочек вызовов. Выходящие за пределы заданной глубины стека вызовы не учитываются при анализе. Отметим, что опция влияет лишь на представление, т. е. работа ядра не ограничивается заданным параметром. Издержки, связанные с цепочкой вызовов можно установить с помощью —call-graph dwarf.

Подразумевается опция —call-graph dwarf при отсутствии —call-graph в командной строке систем с поддержкой анализа DWARF. По умолчанию используется значение из файла /proc/sys/kernel/perf_event_max_stack (при его наличии) для измерений «вживую» (без опции —input/-i) и 127 в остальных случаях.

—min-stack

Устанавливает минимальную глубину стека для анализа цепочек вызовов. Цепочки с меньшей глубиной игнорируются. По умолчанию ограничение не задано.

Подразумевается опция —call-graph dwarf при отсутствии —call-graph в командной строке систем с поддержкой анализа DWARF.

—print-sample

Выводится информация PERF_RECORD_SAMPLE и PERF_SAMPLE_ для точек трассировки raw_syscalls:sys_{enter,exit} с отладочными целями.

—proc-map-timeout

Обработка имеющихся потоков /proc/XXX/mmap может занимать много времени и эта опция позволяет установить тайм-аут (по умолчанию 500 мсек).

—sort-events

Выполнять сортировку по «пакетам» событий. Используется при обнаружении неупорядоченных событий, например при переносе потока на другой CPU в процессе обработки syscall.

—map-dump

Дамп отображений BPF по события, заданным опцией -e, например, augmented_raw_syscalls в tools/perf/examples/bpf/augmented_raw_syscalls.c. В настоящее время это лишь дамп логических значений отображения и целочисленных ключей, но со временем по умолчанию будут выводиться шестнадцатеричные значения с использованием BTF (при доступности), а также будет использоваться функция удобочитаемого вывода с использованием аргументов perf trace для сопоставления целочисленных значений со строками (pid — команда, идентификатор — имя syscall name и т. п.).

Отказы страниц

При трассировке отказов страниц используется приведенных ниже формат

<min|maj>fault [<ip.symbol>+<ip.offset>] ⇒ <addr.dso@addr.offset[1]> (<map type><addr level>).

min/maj указывает второстепенный (minor) или важный (major) отказ;

ip.symbol показывает символ для указателя инструкции (код, приведший к отказу); при отсутствии отладочных символов perf trace будет выводить raw IP¹⁷;

addr.dso показывает объект DSO для отказавшего адреса;

map type имеет значение d (неисполняемые отображения) или x (исполняемые);

addr level имеет значение k (ядро) или dso для пользовательских объектов DSO.

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

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

При указании опции —verbose команда perf trace пытается выводить всю информацию для IP и адреса отказа в форме dso@symbol[2]+offset.

Примеры

Трассировка только важных отказов страниц

$ perf trace --no-syscalls -F

Трассировка syscall, важных и второстепенных отказов страниц

$ perf trace -F all 

1416.547 ( 0.000 ms): python/20235 majfault [CRYPTO_push_info_+0x0] => /lib/x86_64-linux-gnu/libcrypto.so.1.0.0@0x61be0 (x.)

Можно видеть важный отказ в процессе python от CRYPTO_push_info_ routine, произошедший в libcrypto.so.

Трассировка первых 4 системных вызовов open, openat или open_by_handle_at (в будущем могут появиться другие вызовы open*):

$ perf trace -e open* --max-events 4
[root@jouet perf]# trace -e open* --max-events 4 
2272.992 ( 0.037 ms): gnome-shell/1370 openat(dfd: CWD, filename: /proc/self/stat) = 31 
2277.481 ( 0.139 ms): gnome-shell/3039 openat(dfd: CWD, filename: /proc/self/stat) = 65 
3026.398 ( 0.076 ms): gnome-shell/3039 openat(dfd: CWD, filename: /proc/self/stat) = 65 
4294.665 ( 0.015 ms): sed/15879 openat(dfd: CWD, filename: /etc/ld.so.cache, flags: CLOEXEC) = 3

Трассировка первого второстепенного отказа страницы при работе задачи

# perf trace -F min --max-stack=7 --max-events 1 sleep 1 
   0.000 ( 0.000 ms): sleep/18006 minfault [__clear_user+0x1a] => 0x5626efa56080 (?k) 
                                     __clear_user ([kernel.kallsyms]) 
                                     load_elf_binary ([kernel.kallsyms]) 
                                     search_binary_handler ([kernel.kallsyms]) 
                                     __do_execve_file.isra.33 ([kernel.kallsyms]) 
                                     __x64_sys_execve ([kernel.kallsyms]) 
                                     do_syscall_64 ([kernel.kallsyms]) 
                                     entry_SYSCALL_64 ([kernel.kallsyms])

Трассировка следующего второстепенного отказа страницы, который произошел на первом CPU

# perf trace -F min --call-graph=dwarf --max-events 1 --cpu 0 
    0.000 ( 0.000 ms): Web Content/17136 minfault [js::gc::Chunk::fetchNextDecommittedArena+0x4b] => 0x7fbe6181b000 (?.) 
                              js::gc::FreeSpan::initAsEmpty (inlined) 
                              js::gc::Arena::setAsNotAllocated (inlined) 
                              js::gc::Chunk::fetchNextDecommittedArena (/usr/lib64/firefox/libxul.so) 
                              js::gc::Chunk::allocateArena (/usr/lib64/firefox/libxul.so) 
                              js::gc::GCRuntime::allocateArena (/usr/lib64/firefox/libxul.so) 
                              js::gc::ArenaLists::allocateFromArena (/usr/lib64/firefox/libxul.so) 
                              js::gc::GCRuntime::tryNewTenuredThing<JSString, (js::AllowGC)1> (inlined) 
                              js::AllocateString<JSString, (js::AllowGC)1> (/usr/lib64/firefox/libxul.so) 
                              js::Allocate<JSThinInlineString, (js::AllowGC)1> (inlined) 
                              JSThinInlineString::new_<(js::AllowGC)1> (inlined) 
                              AllocateInlineString<(js::AllowGC)1, unsigned char> (inlined) 
                              js::ConcatStrings<(js::AllowGC)1> (/usr/lib64/firefox/libxul.so) 
                              [0x18b26e6bc2bd] (/tmp/perf-17136.map)

Трассировка двух следующих событий sched:sched_switch, четырех событий block:*_plug, следующего block:*_unplug и следующих трех событий net:*dev_queue с глубиной стека не более 16

# perf trace -e sched:*switch/nr=2/,block:*_plug/nr=4/,block:*_unplug/nr=1/,net:*dev_queue/nr=3,max-stack=16/ 
             0.000 :0/0 sched:sched_switch:swapper/2:0 [120] S ==> rcu_sched:10 [120] 
             0.015 rcu_sched/10 sched:sched_switch:rcu_sched:10 [120] R ==> swapper/2:0 [120] 
           254.198 irq/50-iwlwifi/680 net:net_dev_queue:dev=wlp3s0 skbaddr=0xffff93498051f600 len=66 
                                               __dev_queue_xmit ([kernel.kallsyms]) 
           273.977 :0/0 net:net_dev_queue:dev=wlp3s0 skbaddr=0xffff93498051f600 len=78 
                                               __dev_queue_xmit ([kernel.kallsyms]) 
           274.007 :0/0 net:net_dev_queue:dev=wlp3s0 skbaddr=0xffff93498051ff00 len=78
                                               __dev_queue_xmit ([kernel.kallsyms]) 
          2930.140 kworker/u16:58/2722 block:block_plug:[kworker/u16:58] 
          2930.162 kworker/u16:58/2722 block:block_unplug:[kworker/u16:58] 1 
          4466.094 jbd2/dm-2-8/748 block:block_plug:[jbd2/dm-2-8] 
          8050.123 kworker/u16:30/2694 block:block_plug:[kworker/u16:30] 
          8050.271 kworker/u16:30/2694 block:block_plug:[kworker/u16:30]

script

Читает входной файл perf.data (созданный perf record) и выводит записанную трассировку. Существует несколько вариантов использования perf script, описанных ниже.

perf script

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

perf script record <script> <command>

Записывает события, требуемые для perf script report. Параметр <script> указывает имя из списка perf script —list, т. е. имя реального сценария без языкового расширения (например .pl). Если параметр <command> не задан, события записываются с использованием perf record -a.

perf script report <script> [args]

Для запуска сценария <script> и вывода результатов трассировки. Параметр <script> указывает имя из списка perf script —list, т. е. имя реального сценария без языкового расширения (например .pl). Используется вывод perf.data из предыдущего запуска perf script record <script>, который следует сохранить для работы этой команды. Параметр [args] указывает аргументы (в основном необязательные), которых ждет сценарий.

perf script <script> <required-script-args> <command>

Запись событий, нужных для <script> и запуск <script> в режиме live-mode, т. е. без записи данных на диск. Параметр <script> указывает имя из списка perf script —list, т. е. имя реального сценария без языкового расширения (например .pl). Если параметр <command> не задан, события записываются с использованием perf record -a. Если для <script> нужны аргументы, из следует указать до <command>. В этом режиме не поддерживаются необязательные аргументы и если такие аргументы нужны, их можно задать в отдельных командах perf script record и perf script report с выводом результатов записи в stdout, конвейером в stdin для сценария report и опциями -o — и -i — в соответствующих командах.

perf script <top-script>

Запись событий, нужных для <top-script> и запуск <top-script> в режиме live-mode без записи промежуточных результатов на диск. Параметр <top-script> указывает имя из списка perf script —list, т. е. имя реального сценария без языкового расширения (например .pl), которое может быть именем любого сценария с суффиксом top.

Параметр [<record-options>] может передаваться на этап записи perf script record и в варианты live-mode, но не поддерживается для вариантов <top-script> live-mode и perf script report.

Дополнительная информация о сценариях приведена в разделах script-perl и script-python .

Синтаксис

      perf script [<options>] 
      perf script [<options>] record <script> [<record-options>] <command> 
      perf script [<options>] report <script> [script-args] 
      perf script [<options>] <script> <required-script-args> [<record-options>] <command> 
      perf script [<options>] <top-script> [script-args]

Опции

<command>…

Любая команда, разрешенная командным процессором.

-D, —dump-raw-trace=

Вывод подробного дампа данных трассировки.

-L, —Latency=

Вывод атрибутов задержки (запрет irqs/preemption и т. п.).

-l, —list=

Вывод списка доступных сценариев трассировки.

-s [lang], —script=

Обработка данных трассировки указанным сценарием ([lang]:script[.ext]). Если параметр указан вместо имени сценария, выводится список доступных языков сценариев.

-g, —gen-script=

Генерировать стартовый сценарий perf-script.[ext] для данного языка с использованием текущего файла perf.data.

-a

Форсирует сбор данных в масштабе всей системы. Сценарии, запускаемые без параметра <command>, обычно используют опцию -a по умолчанию, а при использовании с <command> эта опция может быть указана отдельно, если нужен сбор данных от системы в целом.

-i, —input=

Задает имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-d, —debug-mode

Выполнять различные проверки, такие как порядок выборок и потерянные события.

-F, —fields

Список полей вывода через запятые — comm, tid, pid, time, cpu, event, trace, ip, sym, dso, addr, symoff, srcline, period, iregs, uregs, brstack, brstacksym, flags, bpf-output, brstackinsn, brstackoff, callindent, insn, insnlen, synth, phys_addr, metric, misc, srccode. Перед списком полей указывается тип трассировки (trace, sw или hw), для индикации типа событий, к которым относится список полей, например -F sw:comm,tid,time,ip,sym или -F trace:time,cpu,trace. Команда

              perf script -F <fields>

эквивалентна

              perf script -F trace:<fields> -F sw:<fields> -F hw:<fields>

т. е. указанные поля относятся ко всем типам событий, если конкретный тип не указан.

В дополнение к переопределению полей можно добавлять и удалять принятые по умолчанию поля. Например,

              -F -cpu,+insn

удаляет поле cpu и добавляет поле insn. Добавление и удаление полей нельзя смешивать с обычным переопределением.

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

              -F trace: -F comm,tid,time,ip,sym

Первая опция -F подавляет события трассировки (список полей пуст — «»), а втора устанавливает для всех типов поля comm,tid,time,ip,sym. В таких случаях выдаются предупреждения вида

              "Overriding previous field request for all events."

В другом наборе

              -F comm,tid,time,ip,sym -F trace:

первая опция -F задает поля для всех событий, а вторая подавляет события трассировки. Пользователь получит сообщение о переопределении и в результате для указанных полей будут выводиться лишь события SW и HW.

Можно добавить и удалить поля лишь для определенного типа. Например,

              -Fsw:-cpu,-period

удалит поля cpu и period для программных событий.

Если при использовании «шаблонной» опции указать поле, которое не недействительно для того или иного типа событий, будет выдано сообщение об игнорировании поля для этого типа. Например,

              $ perf script -F comm,tid,trace 
              'trace' not valid for hardware events. Ignoring.
              'trace' not valid for software events. Ignoring.

Если же указано недействительное поле для конкретного типа, возникает ошибка. Например,

              perf script -v -F sw:comm,tid,trace 
              'trace' not valid for software events.

В этом случае perf script завершает работу по ошибке.

Поле флагов синтезируется и может иметь значение при декодировании Instruction Trace. Флаги bcrosyiABEx указывают ветвление (branch), вызов (call), возврат (return), условие (conditional), системное (system) или асинхронное (asynchronous) событие, прерывание (interrupt), прерывание транзакции (transaction abort), начало (trace begin) и завершение (trace end) трассировки и нахождение в транзакции (in transaction), соответственно. Известные комбинации флагов указываются более изящно, например, call для bc, return для br, jcc для bo, jmp для b, int для bci, iret для bri, syscall для bcs, sysret для brs, async для by, hw int для bcyi, tx abrt для bA, tr strt для bB, tr end для bE. Однако флаг x в таких случаях будет выводиться отдельно, например, jcc (x) для условного ветвления внутри транзакции.

Поле callindent синтезируется и может иметь значение при декодировании Instruction Trace. Для вызовов и возвратов оно будет указывать имя символа, окруженное пробелами для отражения глубины стека.

При декодировании трассировки инструкций insn и insnlen дают байты и размер для текущей инструкции.

Поле synth используется синтезированными событиями, которые могут создаваться при декодировании Instruction Trace.

Пользователь не может задавать отсутствие полей для всех событий, т. е. -F «» недопустимо.

Вывод brstack включает связанную с ветвлениями информацию с необработанными адресами, используя синтаксис /v/v/v/v/cycles, в следующем порядке:

FROM инструкция источника ветвления;

TO инструкция цели ветвления;

M/P/- M — цель или направление ветвления предсказано не верно, P — цель или направление предсказаны, — -не поддерживается;

X/- X — ветвление внутри области транзакции, — — ветвление вне транзакции или не поддерживается;

A/- A — запись прерывания TSX, — — не прерываемая область или не поддерживаемые циклы.

Поле brstacksym похоже на brstack, но адреса FROM и TO выводятся в символьной форме, если это возможно.

При задании brstackinsn выводятся полные ассемблерные последовательности ветвлений для каждой выборки (полный путь исполнения, ведущий к выборке). Для поддержки такой возможности запись данных должна быть выполнена командой perf record с опцией -b или -j any.

Поле brstackoff указывает смещение в конкретный объект dso или двоичный файл.

С опцией metric команда perf script может рассчитывать параметры для периодов выборки подобно perf stat. Для этого нужно указать группу, имеющую множество метрик, с опцией :S для perf record. Тогда perf будет выбирать первое событие и рассчитывать метрики для всех событий в группе. Важно отметить, что рассчитанные параметры дают среднее значение за период выборки а не мгновенное в точке выборки.

Для событий выборки можно выводить поле misc, указав опцию field with F +misc с последующими символами для отображаемых битов, как показано ниже.

              PERF_RECORD_MISC_KERNEL               K 
              PERF_RECORD_MISC_USER                 U 
              PERF_RECORD_MISC_HYPERVISOR           H 
              PERF_RECORD_MISC_GUEST_KERNEL         G 
              PERF_RECORD_MISC_GUEST_USER           g 
              PERF_RECORD_MISC_MMAP_DATA*           M 
              PERF_RECORD_MISC_COMM_EXEC            E 
              PERF_RECORD_MISC_SWITCH_OUT           S 
              PERF_RECORD_MISC_SWITCH_OUT_PREEMPT   Sp 

              $ perf script -F +misc ... 
               sched-messaging  1414 K     28690.636582:       4590 cycles ... 
               sched-messaging  1407 U     28690.636600:     325620 cycles ... 
               sched-messaging  1414 K     28690.636608:      19473 cycles ... 
               поле misc  ___________/

-k, —vmlinux=<file>

Путь к файлу vmlinux.

—kallsyms=<file>

Путь к файлу kallsyms.

—symfs=<directory>

Каталог, от которого начинается поиск файлов с символами.

-G, —hide-call-graph

Отключает вывод цепочек вызовов при отображении символов.

—stop-bt

Выключает отображение графа вызовов по этим символам.

-C, —cpu

-c, —comms=

Задает учет символов лишь в указанных столбцах. Можно использовать файл CSV, заданный параметром file://filename.

—pid=

Задает вывод событий лишь для указанного идентификатора процесса (список разделенных запятыми значений).

—tid=

Задает вывод событий лишь для указанного идентификатора потока (список разделенных запятыми значений).

-I, —show-info

—show-kernel-path

Пытаться преобразовать (resolve) путь [kernel.kallsyms].

—show-task-events

Отображать связанные с задачей события (например, FORK, COMM, EXIT).

—show-mmap-events

Отображать связанные с mmap события (например, MMAP, MMAP2).

—show-namespace-events

Отображать события пространства имен (PERF_RECORD_NAMESPACES).

—show-switch-events

Отображать события переключения контекста (PERF_RECORD_SWITCH и PERF_RECORD_SWITCH_CPU_WIDE).

—show-lost-events

Отображать события потерь (PERF_RECORD_LOST).

—show-round-events

Отображать события законченного цикла (finished round) (PERF_RECORD_FINISHED_ROUND).

—demangle

Восстанавливать имена символов в удобочитаемую форму. По умолчанию включено, отключается —no-demangle.

—demangle-kernel

Восстанавливать имена символов ядра в удобочитаемую форму (для ядер C++).

—header

Показывать заголовок perf.data.

—header-only

Показывать только заголовок perf.data.

—itrace

Задает опции декодирования данных трассировки инструкций:

i синтезировать события инструкций;

b синтезировать события ветвления;

c синтезировать события ветвления (только вызовы);

r синтезировать события ветвления (только возвраты);

x синтезировать события транзакций;

w синтезировать события ptwrite;

p синтезировать события, связанные с питанием;

e синтезировать события, связанные с ошибками;

d создать журнал отладки;

g синтезировать цепочку вызовов (используется с i или x);

l синтезировать записи последнего ветвления (используется с i или x);

s пропустить указанное число записей в начале.

По умолчанию учитываются все события (—itrace=ibxwpe), за исключением perf (—itrace=ce)

i инструкции;

t такты часов;

ms миллисекунды;

us микросекунды;

ns наносекунды (используется по умолчанию).

Можно также указать размер цепочки (по умолчанию 16, максимум 1024) для событий.

Можно указать также число записей последнего ветвления (по умолчанию 64, максимум 1024).

              --itrace=i0nss1000000

обеспечит пропуск первого миллиона инструкций.

Для полного запрета декодирования служит опция —no-itrace.

—full-source-path

Выводит полный путь к файлам исходного кода при выводе номеров строк.

—max-stack

—ns

Задает использование 9 десятичных цифр при отображении времени (т. е. показывать наносекунды).

-f, —force

Не проверять принадлежность.

—time

Поддерживается также указание интервалов в процентах — a%/n,b%/m,… или a%-b%,c%-%d,…

Например, для выбора вторых 10% интервала записи можно использовать команду

              perf script --time 10%/2

Для выбора интервала от 0% до 10% служит команда

              perf script --time 0%-10%

Например, для выбора первых и вторых 10% интервала записи можно использовать команду

              perf script --time 10%/1,10%/2

Для выбора интервалов от 0% до 10% и от 30% до 40% служит команда

              perf script --time 0%-10%,30%-40%

—max-blocks

задает максимальное число программных блоков при выводе с brstackasm для каждой выборки.

—reltime

Задает вывод временных меток от начала трассировки.

—per-event-dump

Создает для событий файлы perf.data.EVENT.dump вместо вывода на stdout (полезно, например, для создания графа кадров).

—inline

—insn-trace

Показывать поток инструкций для трассировки intel_pt. При использовании с —xed будет выполнено реассемблирование.

—xed

Запустить на выходе дизассемблер xed (должен быть установлен).

—call-trace

Показывать поток вызовов для трассировок intel_pt. Процессоры будут чередоваться, но могут быть отфильтрованы опцией -C.

—call-ret-trace

Показывать поток вызовов и возвратов для трассировок intel_pt.

—graph-function

Для itrace задает вывод только указанных функций и вызываемых ими для itrace. Функции указываются через запятые.

script-perl

Эта команда служит для обработки данных трассировки с помощью сценариев Perl и встроенного в perf интерпретатора Perl. Данные считываются из входного файла и обрабатываются указанным сценарием Perl.

Синтаксис

perf script [-s [Perl]:script[.pl] ]

Стартовые сценарии

Запуск команды perf script -g perl из каталога с файлом perf.data приведет к созданию стартового сценария, содержащего обработчик для каждого типа событий в файле трассировки. Будут выведены доступные поля для каждого события в файле трассировки.

Можно также посмотреть типовые примеры в каталоге /usr/libexec/perf-core/scripts/perl. Сценарий check-perf-script.pl, хотя и не дает интересных результатов, пытается выполнить основные функции сценариев.

Обработчики событий

При вызове perf script с использованием сценария трассировки, вызывается заданный пользователем обработчик функций для каждого события трассировки. Если для данного типа события обработчик не определен, событие игнорируется (или передается функции trace_unhandled, описанной ниже).

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

Например, приведенная ниже команда perf record может использоваться для записи всех событий sched_wakeup в системе.

          # perf record -a -e sched:sched_wakeup

Трассировки, предназначенные для обработки сценарием, следует записывать с опцией -a (система в целом).

Файл /sys/kernel/debug/tracing/events/sched/sched_wakeup/format для событий sched_wakep определяет перечисленные ниже поля.

           format: 
                  field:unsigned short common_type; 
                  field:unsigned char common_flags; 
                  field:unsigned char common_preempt_count; 
                  field:int common_pid; 

                  field:char comm[TASK_COMM_LEN]; 
                  field:pid_t pid; 
                  field:int prio; 
                  field:int success; 
                  field:int target_cpu;

Обработчик для этого события определен ниже.

          sub sched::sched_wakeup 
          { 
             my ($event_name, $context, $common_cpu, $common_secs, 
                 $common_nsecs, $common_pid, $common_comm, 
                 $comm, $pid, $prio, $success, $target_cpu) = @_; 
          }

Функция обработки принимает форму subsystem::event_name.

Аргументы $common_* в списке аргументов обработчика — это аргументы, передаваемые всем обработчикам событий. Некоторые из полей соответствуют полям common_* в файле format, часть полей синтезируется, а часть полей common_* не передается каждому обработчику событий в качестве аргументов, но они доступны как библиотечные функции.

Ниже приведено краткое описание инвариантных аргументов событий.

$event_name имя события в текстовой форме.

$context не обрабатываемое значение cookie, используемое при обратных вызовах perf.

$common_cpu процессор, где произошло событие.

$common_secs секунды из временной метки события.

$common_nsecs наносекунды из временной метки события.

$common_pid pid текущей задачи.

$common_comm имя текущего процесса.

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

Выше представлена база для прямого доступа к каждому полю каждого события и это покрывает 90% того, что нужно знать для создания сценариев трассировки. Остальное описано ниже.

Схема сценария

Каждый Perl-сценарий perf script следует начинать с указания пути поиска модулей Perl и операторов use для нескольких модулей поддержки.

           use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/Perf-Trace-Util/lib"; 
           use lib "./Perf-Trace-Util/lib"; 
           use Perf::Trace::Core; 
           use Perf::Trace::Context; 
           use Perf::Trace::Util;

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

trace_begin

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

           sub trace_begin 
           { 
           }

trace_end

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

          sub trace_end 
          { 
          }

trace_unhandled

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

          sub trace_unhandled 
          { 
              my ($event_name, $context, $common_cpu, $common_secs, 
                  $common_nsecs, $common_pid, $common_comm) = @_; 
          }

Далее описываются доступные модули встроенного интерпретатора Perl и связанные с ними функции.

Доступные модули и функции

Здесь описаны функции и переменные, доступные в модулях Perf::Trace::*. Для их использования из данного сценария в него добавляются соответствующие строки use Perf::Trace::XXX.

Perf::Trace::Core

Этот модуль включает некоторые важные для пользовательских сценариев функции.

Функции flag_str и symbol_str представляют удобочитаемые строки для флагов и символьных полей, соответствующие строкам, извлекаемым ил полей print fmt форматных файлов событий:

flag_str($event_name, $field_name, $field_value) возвращает строку, соответствующую $field_value для поля флагов $field_name в $event_name;

symbol_str($event_name, $field_name, $field_value) возвращает строку, соответствующую $field_value для символьного поля $field_name в $event_name.

Perf::Trace::Context

Некоторые из полей в форматном файле события не являются общими, но нужны для сценария.

Модуль Perf::Trace::Context определяет набор функций, которые могут служить для доступа к этим данным в контексте текущего события. Каждая из этих функций ждет переменную $context, которая совпадает с одноименной переменной, передаваемой каждому обработчику событий во втором аргументе.

common_pc($context) возвращает счетчик common_preempt для текущего события;

common_flags($context) возвращает поле common_flags для текущего события;

common_lock_depth($context) возвращает common_lock_depth для текущего события.

Perf::Trace::Util

Различные вспомогательные функции для perf script.

nsecs($secs, $nsecs) возвращает число наносекунд для данной пары «секунды-наносекунды»;

nsecs_secs($nsecs) возвращает число целых секунд из значения в наносекундах;

nsecs_nsecs($nsecs) возвращает число наносекунд, оставшихся после извлечения целых секунд;

nsecs_str($nsecs) возвращает печатаемую строку в форме секунды.наносекунды;

avg($total, $n) возвращает среднее значение на основе суммы и числа значений.

script-python

Обработка данных трассировки в сценарии Python с использованием встроенного в perf интерпретатора Python. Выполняется считывание и обработка входного файла с выводом результатов обработки данных трассировки сценарием Python.

Синтаксис

perf script [-s [Python]:script[.py] ]

Короткий пример

Здесь показан процесс создания рабочего сценария Python, который агрегирует и извлекает полезную информацию из необработанного потока perf script.

В приведенном ниже примере рассмотрены этапы создания сценария syscall-counts, который можно увидеть в списке, выводимом по команде perf script -l. Сценарий также показывает способ интеграции в список сценариев общего пользования perf script, выводимых по этой команде.

Сценарий syscall-counts очень просто, но демонстрирует основные идеи, требуемые для создания полезных сценариев. Ниже представлен пример вывода этого сценария (вместо имен вызовов syscall, которые еще не поддерживаются, указаны номера).

          syscall events: 

          event                                          count 
          ----------------------------------------  ----------- 
          sys_write                                     455067 
          sys_getdents                                    4072 
          sys_close                                       3037 
          sys_swapoff                                     1769 
          sys_read                                         923 
          sys_sched_setparam                               826 
          sys_open                                         331 
          sys_newfstat                                     326 
          sys_mmap                                         217 
          sys_munmap                                       216 
          sys_futex                                        141 
          sys_select                                       102 
          sys_poll                                          84 
          sys_setitimer                                     12 
          sys_writev                                         8 
          15                                                 8 
          sys_lseek                                          7 
          sys_rt_sigprocmask                                 6 
          sys_wait4                                          3 
          sys_ioctl                                          3 
          sys_set_robust_list                                1 
          sys_exit                                           1 
          56                                                 1
          sys_access                                         1

Задача по сути состоит в поддержке значения для каждого syscall, обновляемых при каждом вызове в системе. Сценарий делает это, но сначала нужно записать данные, которые будут обрабатываться этим сценарием. Теоретически есть несколько способов решения задачи.

Можно включить каждое событие в каталоге tracing/events/syscalls, но там более 600 syscall, что выходит за пределы возможностей perf. Однако эти отдельные события syscall будут полезны впредь для детализации отдельных syscall.
Можно включить sys_enter и/или sys_exit в tracing/events/raw_syscalls. Они вызываются для всех syscall и поле id можно использовать для идентификации отдельных syscall.

Для этого сценария нужно знать лишь о входе в syscall, поэтому будет использоваться perf record для записи лишь событий sys_enter.

          # perf record -a -e raw_syscalls:sys_enter 

          ^C[ perf record: Woken up 1 times to write data ] 
          [ perf record: Captured and wrote 56.545 MB perf.data (~2470503 samples) ]

Опции говорят о необходимости собирать данные для каждого события syscall в системе и мультиплексировать вывод от отдельных процессоров в один поток. Этот поток будет записываться в файл perf.data в текущем каталоге.

Имея файл perf.data с нужными данными, можно использовать команду perf script -g для генерации сценария Python, который будет включать обработчик обратных вызовов для каждого типа событий в потоке данных трассировки из perf.data (см. Стартовые сценарии).

# perf script -g python 
generated Python script: perf-script.py

Выходной файл также создается в текущем каталоге и называется perf-script.py. Этот файл приведен ниже.

# perf script event handlers, generated by perf script -g python 
# Licensed under the terms of the GNU GPL License version 2 

# The common_* event handler fields are the most useful fields common to 
# all events.  They don't necessarily correspond to the 'common_*' fields 
# in the format files.  Those fields not available as handler params can 
# be retrieved using Python functions of the form common_*(context). 
# See the perf-script-python Documentation for the list of available functions. 

import os 
import sys 

sys.path.append(os.environ['PERF_EXEC_PATH'] + '/scripts/python/Perf-Trace-Util/lib/Perf/Trace') 

from perf_trace_context import *
from Core import * 

def trace_begin(): 
        print "in trace_begin" 

def trace_end(): 
        print "in trace_end" 

def raw_syscalls__sys_enter(event_name, context, common_cpu, 
        common_secs, common_nsecs, common_pid, common_comm, 
        id, args): 
                print_header(event_name, common_cpu, common_secs, common_nsecs, common_pid, common_comm) 

          print "id=%d, args=%s\n" % (id, args), 

def trace_unhandled(event_name, context, event_fields_dict): 
        print ' '.join(['%s=%s'%(k,str(v))for k,v in sorted(event_fields_dict.items())]) 

def print_header(event_name, cpu, secs, nsecs, pid, comm): 
        print "%-20s %5u %05u.%09u %8u %-20s " % (event_name, cpu, secs, nsecs, pid, comm),

Файл начинается с блока комментариев, за которыми следуют операторы импорта и добавление пути, который следует включать в каждый сценарий perf script.

далее следуют сгенерированные функции trace_begin() и trace_end(), которые вызываются в начале и в конце сценария (см. Схема сценария).

Затем приведены функции обработчиков для всех событий из выходного файла perf record. Функции обработки имеют форму subsystemevent_name и именованные параметры, по одному для каждого поля события. В примере используется лишь одно событие — raw_syscallssys_enter(). Обработчики более подробно описаны ниже.

Финальная пара функций, подобно начальной и завершающей функциям, генерируется для каждого сценария. Функция trace_unhandled() вызывается при обнаружении сценарием в файле perf.data функции, для которой нет конкретного обработчика. Это может быть обусловлено наличием в файле события, которое не представляет интереса или запуском сценария, который не соответствует файлу трассировки.

Сценарий, созданный опцией -g, просто выводит строку для каждого события из потока трассировки, указывающую событие и значения его полей, на stdout. Функция print_header() выводит заголовок.

Затем можно переименовать сценарий и воспользоваться им.

# mv perf-script.py syscall-counts.py 
# perf script -s syscall-counts.py 

raw_syscalls__sys_enter     1 00840.847582083     7506 perf                  id=1, args= 
raw_syscalls__sys_enter     1 00840.847595764     7506 perf                  id=1, args= 
raw_syscalls__sys_enter     1 00840.847620860     7506 perf                  id=1, args= 
raw_syscalls__sys_enter     1 00840.847710478     6533 npviewer.bin          id=78, args= 
raw_syscalls__sys_enter     1 00840.847719204     6533 npviewer.bin          id=142, args= 
raw_syscalls__sys_enter     1 00840.847755445     6533 npviewer.bin          id=3, args=
raw_syscalls__sys_enter     1 00840.847775601     6533 npviewer.bin          id=3, args= 
raw_syscalls__sys_enter     1 00840.847781820     6533 npviewer.bin          id=3, args= 
          . 
          . 
          .

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

          import os 
          import sys 

          sys.path.append(os.environ['PERF_EXEC_PATH'] + \ 
                  '/scripts/python/Perf-Trace-Util/lib/Perf/Trace') 

          from perf_trace_context import * 
          from Core import * 

          def trace_end(): 
                  print "in trace_end" 

          def raw_syscalls__sys_enter(event_name, context, common_cpu, 
                  common_secs, common_nsecs, common_pid, common_comm, 
                  id, args):

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

            syscalls = autodict() 

            try: 
              syscalls[id] += 1 
            except TypeError: 
              syscalls[id] = 1

Объект autodict является специальным словарем Python (реализован в Core.py), поддерживающим автоматически обновляемые хэш-значения Perl в языке Python. Это позволяет назначать вложенные хэш-значения без необходимости создавать промежуточные уровни хэширования при их отсутствии. Например, syscalls[comm][pid][id] = 1 будет создавать промежуточные уровни хэширования и в конце концов присваивать значение 1 хэш-записи для идентификатора (поскольку присваиваемое значение само не является хэш-объектом, начальное значение присваивается в TypeError).

Приведенный выше код помещается в обработчик raw_syscalls__sys_enter() и это фактически дает одноуровневый словарь с идентификатором syscall в качестве ключа и счетчиками.

Функция print_syscall_totals() перебирает записи в словаре и выводит для каждой записи строку с именем syscall (записи содержат идентификаторы syscall, которые передаются функции syscall_name(), преобразующей их в имена). Вывод выполняется после обработки всех событий в файле трассировки путем вызова print_syscall_totals() из обработчика trace_end() в конце сценария.

Окончательный сценарий приведен ниже (функция syscall_name() еще не реализована, поэтому выводятся идентификаторы, а не имена).

import os 
import sys 

sys.path.append(os.environ['PERF_EXEC_PATH'] + '/scripts/python/Perf-Trace-Util/lib/Perf/Trace') 

from perf_trace_context import * 
from Core import * 
from Util import * 

syscalls = autodict() 

def trace_end(): 
        print_syscall_totals() 

def raw_syscalls__sys_enter(event_name, context, common_cpu, 
        common_secs, common_nsecs, common_pid, common_comm, id, args): 
        try: 
                  syscalls[id] += 1 
        except TypeError: 
                  syscalls[id] = 1 

def print_syscall_totals(): 
     if for_comm is not None: 
              print "\nsyscall events for %s:\n\n" % (for_comm), 
     else: 
              print "\nsyscall events:\n\n", 

        print "%-40s  %10s\n" % ("event", "count"), 
        print "%-40s  %10s\n" % ("----------------------------------------", "-----------"), 

        for id, val in sorted(syscalls.iteritems(), key = lambda(k, v): (v, k), reverse = True): 
              print "%-40s  %10d\n" % (syscall_name(id), val),

Сценарий можно запустить командой

          # perf script -s syscall-counts.py

Показанные выше этапы создания и запуска сценариев можно обобщить на любой набор интересующих точек трассировки. Такие точки можно определить путем просмотра списка доступных событий с помощью команды perf list или файлов в /sys/kernel/debug/tracing/events/. Затем трассировка нужных событий записывается с помощью perf record, которой указаны интересующие события, создается базовый сценарий с помощью команды perf script -g python и код сценария редактируется для обработки и отображения интересующих данных.

Полученный в результате сценарий можно сохранить для последующего применения. Разместив файл сценария в нужном месте, вы сможете потом найти его по команде perf script -l.

          # perf script -l 
          List of available trace scripts: 
            wakeup-latency                       system-wide min/max/avg wakeup latency 
            rw-by-file <comm>                    r/w activity for a program, by file 
            rw-by-pid                            system-wide r/w activity 
            syscall-counts                       system-wide syscall counts

Стартовые сценарии

Можно быстро создать базовый сценарий для конкретного набора данных с помощью команды perf script -g python, запущенной из каталога, в котором хранится файл perf.data. Полученный в результате сценарий будет включать обработчики для каждого типа событий в файле трассировки. Эти обработчики просто выводят все поля для каждого события в одну строку.

Можно также воспользоваться сценариями из каталога /usr/libexec/perf-core/scripts/python, где представлено несколько базовых примеров.

Обработчики событий

При вызове perf script со сценарием трассировки вызывается определенная пользователем функция обработки для каждого события. Если для какого-либо событие обработчик не задан, событие игнорируется или передается функции trace_unhandled.

Например, приведенная ниже команда perf record может использоваться для записи всех событий sched_wakeup в системе.

          # perf record -a -e sched:sched_wakeup

Трассировки, предназначенные для обработки сценарием, следует записывать с опцией -a (система в целом).

Файл /sys/kernel/debug/tracing/events/sched/sched_wakeup/format для событий sched_wakep определяет перечисленные ниже поля.

           format: 
                  field:unsigned short common_type; 
                  field:unsigned char common_flags; 
                  field:unsigned char common_preempt_count; 
                  field:int common_pid; 

                  field:char comm[TASK_COMM_LEN];
                  field:pid_t pid; 
                  field:int prio; 
                  field:int success; 
                  field:int target_cpu;

Обработчик для этого события определен ниже.

          def sched__sched_wakeup(event_name, context, common_cpu, common_secs, 
                 common_nsecs, common_pid, common_comm, 
                 comm, pid, prio, success, target_cpu): 
                 pass

Функция обработки принимает форму subsystem__event_name.

Аргументы common_* в списке аргументов обработчика — это аргументы, передаваемые всем обработчикам событий. Некоторые из полей соответствуют полям common_* в файле format, часть полей синтезируется, а часть полей common_* не передается каждому обработчику событий в качестве аргументов, но они доступны как библиотечные функции.

Ниже приведено краткое описание инвариантных аргументов событий.

event_name имя события в текстовой форме.

context не обрабатываемое значение cookie, используемое при обратных вызовах perf.

common_cpu процессор, где произошло событие.

common_secs секунды из временной метки события.

common_nsecs наносекунды из временной метки события.

common_pid pid текущей задачи.

common_comm имя текущего процесса.

Схема сценария

Каждый сценарий Python для perf script должен начинаться с установки пути поиска модулей Python и импорта нескольких модулей поддержки, как показано ниже

import os 
import sys 

sys.path.append(os.environ['PERF_EXEC_PATH']+'/scripts/python/Perf-Trace-Util/lib/Perf/Trace') 

from perf_trace_context import * 
from Core import *

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

trace_begin

          def trace_begin(): 
              pass

trace_end

          def trace_end(): 
              pass

trace_unhandled

          def trace_unhandled(event_name, context, event_fields_dict): 
              pass

Далее описываются встроенные модули Python для perf script и их функции.

Доступные модули и функции

Ниже описаны функции и переменные, доступные в модулях Python для perf script. Для использования их из того или иного модуля нужно добавить в него строку import с именем импортируемого сценария.

Core.py

Модуль содержит функции, требуемые для пользовательских сценариев.

Функции flag_str и symbol_str обеспечивают удобочитаемое представление полей флагов и символьных полей. Это соответствует строкам и значениям, извлекаемым из полей print fmt в форматных файлах событий:

flag_str(event_name, field_name, field_value) возвращает строку, соответствующую field_value для поля флагов в field_name имени события event_name;
symbol_str(event_name, field_name, field_value) возвращает строку, соответствующую field_value для символьного поля field_name события event_name.

Функция autodict возвращает специальный словарь Python, реализующий автоматически обновляемые хэш-значения Perl в языке Python. Это позволяет присваивать вложенные хэш-значения без проблем, связанных с промежуточными уровнями, если они отсутствуют.

autodict() возвращает экземпляр словаря.

perf_trace_context

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

common_pc(context) возвращает счетчик common_preempt для текущего события;

common_flags(context) возвращает common_flags для текущего события;

common_lock_depth(context) возвращает common_lock_depth для текущего события.

Util.py

Вспомогательные функции для использования с perf script:

nsecs(secs, nsecs) возвращает общее число наносекунд для данной пары секунды-наносекунды;

nsecs_secs(nsecs) возвращает число целых секунд, заданных в наносекундах;

nsecs_nsecs(nsecs) возвращает число наносекунд, оставшихся после целых секунд;

nsecs_str(nsecs) возвращает печатаемую строку в форме секунды.наносекунды;

avg(total, n) возвращает среднее значение по сумме и количеству значений. number of values

Поддерживаемые поля

В настоящее время поддерживаются поля ev_name, comm, pid, tid, cpu, ip, time, period, phys_addr, addr, symbol, dso, time_enabled, time_running, values, callchain, brstack, brstacksym, datasrc, datasrc_decode, iregs, uregs, weight, transaction, raw_buf, attr.

Некоторые поля имею субэлементы:

brstack — from, to, from_dsoname, to_dsoname, mispred, predicted, in_tx, abort, cycles;

brstacksym — from, to, pred, in_tx, abort (преобразованная строка).

Например, можно использовать приведенный ниже код для вывода значений brstack «from», «to», «cycles».

if brstack in dict: for entry in dict[brstack]: print "from %s, to %s, cycles %s" % (entry["from"], entry["to"], entry["cycles"])

timechart

Инструмент для визуализации поведения системы под нагрузкой. Есть 2 варианта применения perf timechart.

perf timechart record <command>

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

perf timechart

Трассировка в файл SVG¹⁸, который можно просматривать в таких программах как Inkscape. В зависимости от событий в файле perf.data режим timechart будет показывать события планировщика, процессоров и ввода-вывода.

В режиме IO каждая панель включает два графика (верхний и нижний). На верхнем показаны входящие события (чтение дисков, входящие из сети пакеты), а на нижнем — исходящие (запись на диск, передача пакетов в сеть). Имеются также панели, показывающие время пребывания программы в системных вызовах poll/epoll/select.

Опции режима timechart

-o, —output=

Имя выходного файла (по умолчанию output.svg).

-i, —input=

Имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-w, —width=

Выбор ширины для файла SVG (по умолчанию 1000).

-P, —power-only

Вывод только раздела CPU.

-T, —tasks-only

Не выводить смены состояния процессоров.

-p, —process

Выбор процессов для вывода (по имени или PID)

-f, —force

Выполнять без вопросов.

—symfs=<directory>

Поиск файлов с символами относительно указанного каталога.

-n, —proc-num

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

-t, —topology

Сортировать CPU в соответствии с топологией.

—highlight=<duration_nsecs|task_name>

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

—io-skip-eagain

Не показывать события EAGAIN IO.

—io-min-time=<nsecs>

Выводить мелкие события, как будто они имели минимальную длительность. Это полезно для мелких и коротких операций ввода-вывода. Можно задать время в миллисекундах (суффикс ms) или микросекундах (us). По умолчанию используется 1000000 нсек (1 мсек).

—io-merge-dist=<nsecs>

Объединять события, разделенные интервалом merge-dist нсек. Это снижает число фигур на рисунке SVG и делает его более читаемым. Можно задать время в миллисекундах (суффикс ms) или микросекундах (us). По умолчанию используется 1000 нсек (1 мксек).

Опции режима record

-P, —power-only

Записывать только связанные с питанием события.

-T, —tasks-only

Записывать только связанные с задачами события.

-I, —io-only

Записывать только связанные с вводом-выводом события.

-g, —callchain

Записывать граф вызовов.

Примеры

$ perf timechart record git pull 

          [ perf record: Woken up 13 times to write data ] 
          [ perf record: Captured and wrote 4.253 MB perf.data (~185801 samples) ] 

$ perf timechart 

          Written 10.2 seconds of trace to output.svg.

Запись временного графика для системы в целом

          $ perf timechart record

затем генерация timechart с выделением задач gcc

          $ perf timechart --highlight gcc

Запись событий ввода-вывода в масштабе системы

          $ perf timechart record -I

затем генерация timechart

          $ perf timechart

mem

Выводит профиль доступа к памяти. Команда perf mem record выполняет указанную за ней команду и собирает данные в файл perf.data. Могут применяться опции perf record. Команда perf mem report выводит результат профилирования, вызывая perf report с нужным набором опций для вывода профиля доступа к памяти. По умолчанию делаются выборки load и store. Опция -t позволяет выбрать один из вариантов.

В системах Intel выводится задержка использования, а не чистая задержка load или store. Задержка использования включает задержки в очередях, а не только задержки в подсистеме памяти.

Синтаксис

perf mem [<options>] (record [<command>] | report)

Опции

<command>…

Любая команда, понятная командному процессору.

-i, —input=<file>

Имя входного файла.

-f, —force

Не проверять владение.

-t, —type=<type>

Задает тип операции в памяти — load или store (по умолчанию оба — load,store).

-D, —dump-raw-samples

Дамп необработанных выборок в формате, пригодном для анализа, по одной выборке в строке.

-x, —field-separator=<separator>

Задает разделитель полей для вывода необработанного дампа (опция -D). По умолчанию пробел.

-C, —cpu=<cpu>

-U, —hide-unresolved

Выводить только записи, преобразованные в символы.

-p, —phys-data

Физические адреса выборки при записи/отчете.

Опции записи

-e, —event <event>

Селектор событий. Для просмотра списка доступных событий служит команда perf mem record -e list.

-K, —all-kernel

Настроить все используемые события на работу в пространстве ядра.

-U, —all-user

Настроить все используемые события на работу в пользовательском пространстве.

-v, —verbose

Подробный вывод (ошибки открытия счетчиков и т. п.).

—ldlat <n>

Указать желаемую загрузку для событий load. (только x86).

Кроме того можно использовать все опции perf report, а для записи — опции perf record.

c2c

Анализатор данных C2C¹⁹ и HITM, позволяющий отслеживать «соперничество» при кэшировании.

В системах x86 инструмент работает на основе задержек загрузки и событий хранения, предоставляемых процессорами Intel. В системах PowerPC используются выборки случайных инструкций с использованием порога. Эти события обеспечивают адрес доступа к памяти, тип доступа (load и store), задержку (в машинных тактах) доступа для загрузки (load).

Инструмент c2c позволяет записывать эти данные и выводить отчет о деталях доступа для строк кэширования с максимальным числом столкновения (наибольшим числом обращений HITM). Дополнительную информацию о работе с инструментами c2c можно найти по ссылке https://joemario.github.io/blog/2016/09/01/c2c-blog/.

Синтаксис

perf c2c record [<options>] <command> 
perf c2c record [<options>] - [<record command options>] <command> 
perf c2c report [<options>]

Опции record

-e, —event=

Выбирает событие PMU. Список доступных событий выводится по команде perf mem record -e list.

-v, —verbose

Подробный вывод (ошибки открытия счетчиков и т. п.).

-l, —ldlat

Измерение задержки load (только x86).

-k, —all-kernel

Настройка всех используемых событий на работу в пространстве ядра.

-u, —all-user

Настройка всех используемых событий на работу в пользовательском пространстве.

Опции report

-k, —vmlinux=<file>

Путь к файлу vmlinux.

-v, —verbose

Подробный вывод (ошибки открытия счетчиков и т. п.).

-i, —input

Задает входной файл для обработки.

-N, —node-info

Выводить в отчете дополнительную информацию об узде (см. Информация об узле).

-c, —coalesce

Задает сортировку полей для одного вывода cacheline. Доступны поля tid, pid, iaddr, dso (см. Объединение).

-g, —call-graph

Задает параметры цепочек вызовов (см. perf report).

—stdio

Задает вывод в stdio (см. ниже).

—stats

Выводить только таблицы статистики и форсировать режим stdio.

—full-symbols

Выводить символы в полном размере.

—no-source

Не выводить столбец Source:Line.

—show-all

Показывать все собранные строки HITM независимо от порога 0,0005 %.

-f, —force

Не проверять принадлежность.

-d, —display

Переключиться на тип HITM (rmt, lcl) для вывода и сортировки.

Запись C2C

Команда perf c2c record устанавливает опции, связанные с анализом HITM cacheline и вызывает команду perf record.

По умолчанию применяются опции, показанные ниже.

          -W,-d,--phys-data,--sample-cpu

Если опция -e не задает иного, в x86 отслеживаются события

          cpu/mem-loads,ldlat=30/P 
          cpu/mem-stores/P

а в PowerPC

          cpu/mem-loads/ 
          cpu/mem-stores/

Пользователь может задать любые опции perf record после маркера —, например,

          $ perf c2c record -- -g -a

Опции записи описаны выше.

Отчет C2C

Команда perf c2c report выводит результаты анализа и может работать в двух режимах — stdio и TUI (по умолчанию). Сначала все данные сортируются по адресам cacheline, затем сохраняются детали доступа для каждой строки кэша и далее строки кэша сортируются с учетом пользовательских настроек.

В общем случае вывод содержит два базовых представления — список самых «дорогих» cacheline и детали смещения для каждой строки кэша.

В первом представлении для каждой cacheline в обоих режимах выводятся перечисленные ниже данные.

Index

Индекс (отсчет с 0) cacheline.

Cacheline

Адрес cacheline (шестнадцатеричный).

Total records

Суммарное число обращений ко всем cacheline.

Rmt/Lcl Hitm

Доля данной строки в общем числе удаленных/локальных обращений HITM (в процентах)

LLC Load Hitm — Total, Lcl, Rmt

Общее, локальное и удаленное число load HITM

Store Reference — Total, L1Hit, L1Miss

Total — все обращения для записи (store);

L1Hit — записи, затрагивающие L1;

L1Miss — записи, не затрагивающие L1.

Load Dram

Число локальных и удаленных обращений к DRAM.

LLC Ld Miss

Общее число обращений с отсутствующим LLC²⁰.

Total Loads

Суммарное число обращений load.

Core Load Hit — FB, L1, L2

Счетчик обращений load в FB²¹ кэша L1 и L2.

LLC Load Hit — Llc, Rmt

Счетчик обращений LLC и Remote.

Во втором представлении выводятся перечисленные ниже данные.

HITM — Rmt, Lcl

Доля (в %) обращений Remote/Local HITM для данного смещение в cacheline.

Store Refs — L1 Hit, L1 Miss

Доля (в %) обращений с наличием и отсутствием записи в кэше L1 для данного смещение в cacheline.

Data address — Offset

Адрес смещения.

Pid

Идентификатор процесса, отвечающего за обращение.

Tid

Идентификатор потока, отвечающего за обращение.

Code address

Адрес кода, ответственного за обращение.

cycles — rmt hitm, lcl hitm, load

Сумма машинных тактов для обращений Remote/Local HITM и базовых load.

cpu cnt

Число процессоров, участвовавших в доступе.

Symbol

Символ кода, связанный со значением Code address.

Shared Object

Имя общего объекта, связанного со значением Code address.

Source:Line

Информация источника, относящаяся к значению Code address.

Node

Узлы, участвующие в обращении (см. Информация об узле).

Информация об узле

Поле Node указывает узлы, к которым был доступ по данному смещению cacheline. Вывод представляется в 3 варианта — идентификаторы узлов через запятые, идентификаторы узлов со статистикой для каждого в формате Node{cpus %hitms %stores}, идентификаторы узлов со список затронутых CPU в формате Node{cpu list}. Пользователь может выбрать вариант с помощью опции -N или клавиши n в интерактивном режиме TUI.

Объединение

Пользователь может задать способ сортировки смещения для cacheline. Ниже перечислены поля, доступные для управления выходными полями смещения caheline:

tid объединение по TID;

pid объединение по PID;

iaddr объединение по адресам кода с выводом полей Code address, Code symbol, Shared Object, Source line;

dso объединение по общим объектам.

По умолчанию объединение происходит по значениям поля pid,iaddr.

Вывод STDIO

В режиме stdio результаты отображаются на стандартном устройстве вывода и включают перечисленные таблицы.

Trace Event Information

Общая статистика обращений к памяти.

Global Shared Cache Line Event Information

Общая статистика разделяемых cacheline.

Shared Data Cache Line Table

Список наиболее «дорогих» cacheline.

Shared Cache Line Distribution Pareto

Список всех смещений доступа для каждой cacheline.

Вывод TUI

В режиме TUI обеспечивается интерактивный интерфейс для работы со списком cacheline и вывода деталей смещения. Справку о работе с интерфейсом можно получить, нажав клавишу ?.

kmem

Инструмент для трассировки и измерения производительности операций с памятью в ядре. Работает в 2 вариантах.

perf kmem record <command>

Запись событий kmem при выполнении произвольной задачи²².

perf kmem stat

Статистический отчет о работе памяти ядра.

Синтаксис

perf kmem {record|stat} [<options>]

Опции

-i <file>, —input=<file>

Задает входной файл (по умолчанию perf.data, если stdin не является fifo).

-f, —force

Не проверять принадлежность.

-v, —verbose

Подробный вывод (адреса символов и т. п.).

—caller

Вывод статистики по callsite.

—alloc

Вывод статистики по назначениям (allocation).

-s <key[,key2…]>, —sort=<key[,key2…]>

Сортировка вывода (по умолчанию frag,hit,bytes для slab и bytes, hit для страницы). Возможна сортировка по ключам ptr, callsite, bytes, hit, pingpong, frag для slab и page, callsite, bytes, hit, order, migtype, gfp для страницы. Перед этой опцией следует указывать одну из опций выбора режима, т. е. —slab, —page, —alloc и/или —caller.

-l <num>, —line=<num>

Выводить только num строк.

—raw-ip

Выводить raw ip вместо символов.

—slab

Анализ событий распределителя SLAB.

—page

Анализ событий распределителя страниц.

—live

Показывать страницу статистики «вживую». Выводится общая статистика принятая по умолчанию, но с показом распределенных в текущий момент страниц. Требуется установка опции —page.

—time=<start>,<stop>

Анализ выборок из временного окна <start>,<stop>. Время указывается в формате секунды.микросекунды. Если начало не указано (,x.y), анализ выполняется от начала файла, при опущенном времени завершения (x.y,) анализ выполняется до конца файла.

lock

Анализ блокировок в системе.

perf lock record <command>

Записывает события блокировок от начала до завершение <command>, создавая файл perf.data с записью событий блокировки.

perf lock report

Статистический отчет.

perf lock script

Вывод необработанных событий блокировки.

perf lock info

Вывод метаданных (потоки или адреса экземпляров блокировки).

Синтаксис

perf lock {record|report|script|info}

Опции

-i, —input=<file>

Имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-v, —verbose

Подробный вывод (адреса символов и т. п.).

-D, —dump-raw-trace

Дамп необработанной трассировки в формате ASCII.

-f, —force

Выполнять без лишних вопросов.

Опции записи

-k, —key=<value>

Ключ сортировки — acquired (используется по умолчанию), contended, avg_wait, wait_total, wait_max, wait_min.

Опции отчета

-t, —threads

Дамп списка протоколов в perf.data.

-m, —map

Дамп отображения экземпляров блокировки (address:name table)

sched

Инструмент для трассировки и измерения свойств (задержки) планировщиков. Команда поддерживает несколько режимов, описанных ниже.

perf sched record <command>

Запись событий планирования для произвольной задачи.

perf sched latency

Отчет о задержках планирования по задачам и другие свойства планирования при выполнении задания.

perf sched script

Просмотр подробной трассировки задачи, которая была записана (в настоящее время псевдоним perf script).

perf sched replay

Имитация задачи, записанной с помощью perf sched record, путем запуска макетных потоков, имитирующих задачу, на основе записанной трассировки. Эти потоки могут воспроизводить временные характеристики задачи (время работы CPU, картина сна) при ее записи и могут многократно повторяться для измерения производительности.

perf sched map

Вывод текстового представления переключения контекста задачи, записанного с помощью команды perf sched record. Выводятся столбцы для отдельных CPU и двухсимвольные сокращения для работающих на CPU задач. Символ * указывает CPU, на котором произошло событие переключения контекста, а точка — бездействующий CPU.

perf sched timehist

Анализ событий планирования.

Синтаксис

perf sched {record|latency|map|replay|script|timehist}

Опции

-i, —input=<file>

Имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-v, —verbose

Подробный вывод (адреса символов и т. п.).

-D, —dump-raw-trace=

Вывод подробного дампа данных планирования.

-f, —force

Выполнять без лишних вопросов.

Опции perf sched map

—compact

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

—cpus

Показывать записи действий для указанных CPU.

—color-cpus

Отметить цветом указанные процессоры.

—color-pids

Отметить цветом указанные pid.

Опции perf sched timehist

-k, —vmlinux=<file>

Путь к файлу vmlinux.

—kallsyms=<file>

Путь к файлу kallsyms.

-g, —call-graph

Выводить цепочки вызовов при их наличии (принято по умолчанию).

—max-stack

Максимальное число функций, показываемых в обратной трассировке (по умолчанию 5)

-p=, —pid=

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

-t=, —tid=

Показывать только события для указанных через запятые идентификаторов потоков.

-s, —summary

Показывать только сводку событий планирования по потокам с выводом минимального, максимального и среднего времени работы (в секундах) и связанного stddev.

-S, —with-summary

Показывать все события планирования и сводку по потокам с выводом минимального, максимального и среднего времени работы (в секундах) и связанного stddev.

—symfs=<directory>

Поиск файлов с символами относительно указанного каталога.

-V, —cpu-visual

Выводить визуальные подсказки для переключения планирования между CPU — i указывает бездействие (idle), s — события планировщика.

-w, —wakeups

Показывать события пробуждения.

-M, —migrations

Показывать события переноса (migration).

-n, —next

Показывать следующую задачу.

-I, —idle-hist

Показывать только события, связанные с бездействием.

—time

Анализировать только выборки в интервале <start>,<stop>, указанном в формате секунды.микросекунды. Если начало не указано (,x.y) данные анализируются от начала файла. Если не указно время завершения (x.y,), данные анализируются до конца файла.

—state

Показывать состояние задачи при переключении.

Пример применения

perf sched record -- sleep 1 
perf sched timehist

По умолчанию выводятся отдельные события планирования, включая время ожидания (wait time — время между событием sched-out и следующим событием sched-in для задачи), задержку планирования задачи (sch delay — время между пробуждением и началом работы) и время работы задачи (run time).

                      time    cpu  task name             wait time  sch delay   run time 
                                   [tid/pid]                (msec)     (msec)     (msec) 
            -------------- ------  --------------------  ---------  ---------  --------- 
              79371.874569 [0011]  gcc[31949]                0.014      0.000      1.148 
              79371.874591 [0010]  gcc[31951]                0.000      0.000      0.024 
              79371.874603 [0010]  migration/10[59]          3.350      0.004      0.011
              79371.874604 [0011]  <idle>                    1.148      0.000      0.035 
              79371.874723 [0005]  <idle>                    0.016      0.000      1.383 
              79371.874746 [0005]  gcc[31949]                0.153      0.078      0.022 
          ...

Время указано в формате миллисекунды.микросекунды.

kvm

Инструмент для трассировки и измерения производительности гостевых ОС KVM. Имеется несколько вариантов использования perf kvm, описанных ниже.

perf kvm [options] top <command>

Для генерации и вывода профиля производительности гостевой ОС в реальном масштабе времени при выполнении произвольной задачи.

perf kvm record <command>

Для записи профиля производительности при выполнении произвольной задачи с сохранением данных в файле perf.data. По умолчанию для поведения perf kvm используется опция —guest, поэтому если на входе нет ни —host, ни —guest, файл данных perf будет иметь имя perf.data.guest. Если задана опция —host, файл получит имя perf.data.kvm. Если нужно записать данные в файл perf.data.host, следует указать —host —no-guest. Это поведение конкретно описано ниже.
без указания -> perf.data.guest
—host -> perf.data.kvm
—guest -> perf.data.guest
—host —guest -> perf.data.kvm
—host —no-guest -> perf.data.host

perf kvm report

Для вывода информации профиля производительности, записанного по команде perf kvm record.

perf kvm diff

Для вывода различий производительности между двумя файлами perf.data, полученными с помощью perf record.

perf kvm buildid-list

Для вывода идентификаторов сборки из файла perf.data, которые могут применяться другими инструментами для извлечения пакетов с соответствующими таблицами символов, используемых командой perf report. Поскольку идентификаторы сборки считываются из /sys/kernel/notes в ОС, для получения списка идентификаторов сборки гостевой ОС следует убедиться, что файл perf.data был получен по команде perf kvm record с опцией —guestmount.

perf kvm stat <command>

Для запуска команды и сбора счетчиков статистики.

В частности, perf kvm stat record/report выполняет анализ статистики событий KVM. В настоящее время поддерживаются события vmexit, mmio (только x86) и ioport (только x86). Команда perf kvm stat record <command> записывает события KVM и события между началом и завершением команды <command>.

Эта команда создает файл с результатами трассировки событий KVM.

perf kvm stat report

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

perf kvm stat live

Выводит статистические данные «вживую» (подобно record + report, но с обновлением данных в процессе работы).

Синтаксис

perf kvm [--host] [--guest] [--guestmount=<path> 
              [--guestkallsyms=<path> --guestmodules=<path> | --guestvmlinux=<path>]] 
              {top|record|report|diff|buildid-list} [<options>] 
      perf kvm [--host] [--guest] [--guestkallsyms=<path> --guestmodules=<path> 
              | --guestvmlinux=<path>] {top|record|report|diff|buildid-list|stat} [<options>] 
      'perf kvm stat [record|report|live] [<options>]

Опции

-i, —input=<path>

Имя входного файла.

-o, —output=<path>

Имя выходного файла.

—host

Профиль производительности на стороне хоста.

—guest

Профиль производительности на стороне гостевой системы.

—guestmount=<path>

Каталог монтирования корня файловой системы гостевой ОС. Пользователи монтируют корень гостевой файловой системы по пути <path>, указывая метод доступа к файловой системе (обычно sshfs). Рассмотрим для примера две гостевых ОС, одна из которых имеет pid 8888, другая — 9999.

#mkdir /guestmount; cd/guestmount 
#sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/ 
#sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/ 
#perf kvm --host --guest --guestmount=~/guestmount top

—guestkallsyms=<path>

Копия файла гостевой ОС /proc/kallsyms. Команда perf kvm читает его для получения символов гостевого ядра. Пользователи копируют это из гостевой ОС.

—guestmodules=<path>

Копия файла гостевой ОС /proc/modules. Команда perf kvm читает его для получения информации модулей ядра. Пользователи копируют это из гостевой ОС.

—guestvmlinux=<path>

Файл vmlinux ядра гостевой ОС.

-v, —verbose

Подробный вывод (ошибки открытия счетчиков и т .п.).

Опции статистического отчета

—vcpu=<value>

Анализ событий на заданных виртуальных процессорах (по умолчанию все vcpu).

—event=<value>

Событие для анализа — vmexit, mmio (только x86), ioport (только x86). По умолчанию vmexit.

-k, —key=<value>

Ключ сортировки — sample (используется по умолчанию, по номеру выборки), time (по среднему времени).

-p, —pid=

Анализ событий только для указанных через запятые идентификаторов процессов.

Опции статистики “вживую”

-d, —display

Интервал обновления в секундах.

-m, —mmap-pages=

Число страниц данных mmap (должно быть степенью 2) или размер с суффиксом B/K/M/G (округляется до ближайшей степени 2).

-a, —all-cpus

Сбор данных от всех CPU.

-p, —pid=

Анализ событий лишь для указанных через запятые идентификаторов процессов.

—vcpu=<value>

Анализ событий на указанном виртуальном процессоре (по умолчанию учитываются все vcpu).

—event=<value>

Событие для анализа — vmexit, mmio (только x86), ioport (только x86). По умолчанию vmexit.

-k, —key=<value>

Ключ сортировки — sample (принят по умолчанию, сортировка по числу выборок), time (по среднему времени).

—duration=<value>

Показывать события, отличные от HLT (только x86) или Wait (только s390) с продолжительностью больше указанного значения.

—proc-map-timeout

Обработка имеющихся потоков /proc/XXX/mmap может занимать продолжительное время. Эта опция позволяет задать тайм-аут для такой обработки (по умолчанию 500 мсек).

diff

Команда обеспечивает сравнение двух и более файлов perf.data и выводит различия между результатами, собранными с помощью команд perf record.

Если файлы не заданы, сравниваются perf.data.old и perf.data.

Дифференциальный профиль выводится только для событий, присутствующих в обоих файлах perf.data.

Если параметры сортировки не заданы, вывод сортируется по значениям dso и symbol. Поскольку файлы perf.data могут происходить от разных двоичных файлов, адреса символов могут различаться. Поэтому perf diff сравнивает имена.

Синтаксис

perf diff [baseline file] [data file1] [[data file2] ... ]

Опции

-D, —dump-raw-trace

Дамп необработанной (raw) трассировки в формате ASCII.

—kallsyms=<file>

Путь к файлу kallsyms.

-m, —modules

Загружать символы модуля (работает только с опцией -k и «живым» ядром).

-d, —dsos=

Учитываются символы лишь указанных DSO. Можно использовать файл CSV, заданный параметром file://filename. Эта опция будет влиять на значения процентов в столбцах Baseline/Delta (см. —percentage).

-C, —comms=

Учитываются лишь символы в указанных столбцах. Можно использовать файл CSV, заданный параметром file://filename. Эта опция будет влиять на значения процентов в столбцах Baseline/Delta (см. —percentage).

-S, —symbols=

Учитываются лишь указанные параметром символы. Можно использовать файл CSV, заданный параметром file://filename. Эта опция будет влиять на значения процентов в столбцах Baseline/Delta (см. —percentage).

-s, —sort=

Сортировать по ключам — pid, comm, dso, symbol, cpu, parent, srcline (см. одноименную опцию команды perf report).

-t, —field-separator=

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

-v, —verbose

Подробный вывод (например, необработанные счетчики в дополнение к разнице).

-q, —quiet

Не выводить сообщений (отменяет -v).

-f, —force

Не проверять принадлежность.

—symfs=<directory>

искать файлы с символами относительно указанного каталога.

-b, —baseline-only

Показывать только элементы, соответствующие базовой линии.

-c, —compute

Выбор метода расчета различий — delta (приращение), ratio (отношение), wdiff, delta-abs (абсолютное приращение, принято по умолчанию). Принятое по умолчанию поведение можно изменить в конфигурационной переменной diff.compute. Методы сравнения описаны ниже.

-p, —period

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

-F, —formula

Показывать формулу расчета.

-o, —order

Задает номер столбца для сортировки расчета. Значение 0 задает сортировку по базовой линии издержек, а 1 (принято по умолчанию) по рассчитанным значениям столбца 1 (данные из первого файла, отличные от базовых).

Значения больше 1 могут использоваться только при достаточном числе файлов. Принятое по умолчанию значение можно изменить в переменной diff.order.

—percentage

Задает способ отображения процента издержек для отфильтрованных записей. Фильтры можно задать опциями —comms, —dsos, —symbols.

—time

Задает анализ выборок лишь из временного окна, заданного в процентах — a%/n,b%/m,… или a%-b%,c%-%d,…

Например, для выбора вторых 10% интервала записи можно использовать команду

              perf diff --time 10%/2

Для выбора интервала от 0% до 10% служит команда

              perf diff --time 0%-10%

Например, для выбора первых и вторых 10% интервала записи можно использовать команду

              perf diff --time 10%/1,10%/2

Для выбора интервалов от 0% до 10% и от 30% до 40% служит команда

              perf diff --time 0%-10%,30%-40%

Поддерживается также анализ выборок из временного окна <start>,<stop>. Время указывается в формате секунды.микросекунды. Если время начала не указано (т. е. ,x.y), анализ начинается с начала файла. Если время окончания не указано (т. е. x.y,), анализ выполняется до конца файла. Строка указания времени имеет форму ‘a1.b1,c1.d1:a2.b2,c2.d2’. Для разделения временных меток разных файлов perf.data используется двоеточие (:).

Например, для получения временных меток из perf script можно использовать команды

              perf script -i perf.data.old 
                mgen 13940 [000]  3946.361400: ... 

              perf script -i perf.data 
                mgen 13940 [000]  3971.150589 ... 

              perf diff --time 3946.361400,:3971.150589,

Анализируется файл perf.data.old от метки 3946.361400 до конца файла и файл perf.data от метки 3971.150589 до конца файла.

—cpu

Сравнивать только выборки для указанных CPU. Процессоры можно указать списком через запятые (0,1) или диапазоном (0-2) без пробелов. По умолчанию учитываются все CPU.

—pid=

Сравнивать только выборки для указанных через запятые идентификаторов процессов.

—tid=

Сравнивать лишь выборки для указанных через запятые идентификаторов потоков.

Сравнение

Сравнение выполняется с базовым файлом, из которого последовательно считываются выборки. Для этих выборок выполняется поиск соответствия во всех остальных файлах perf.data, указанных в команде. Если парная запись найдена, выполняются указанные расчеты и выводится результат.

Все выборки в файлах perf.data, не соответствующие выборкам в базовом файле, отображаются с незаполненным столбцом baseline и могут включать результаты расчета (приращение) в своем столбце.

Рассмотрим пример, где файл A включает выборки f1, f2, f3, f4, f6, файл B — выборки f2, f4, f5, а файл C — f1, f2, f5. Ниже приведены возможные варианты вывода для разных команд.

```
perf diff A B C
```

              baseline/A compute/B compute/C  samples 
              --------------------------------------- 
              b                    x          f1 
              b          x         x          f2 
              b                               f3 
              b          x                    f4 
              b                               f6 
                         x         x          f5

```
perf diff B A C
```

              baseline/B compute/A compute/C  samples 
              --------------------------------------- 
              b          x         x          f2 
              b          x                    f4 
              b                    x          f5 
                         x         x          f1 
                         x                    f3 
                         x                    f6

```
perf diff C B A
```

              baseline/C compute/B compute/A  samples 
              --------------------------------------- 
              b                    x          f1 
              b          x         x          f2 
              b          x                    f5 
                                   x          f3 
                         x         x          f4 
                                   x          f6

Методы сравнения

delta

В этом случае выводится столбец Delta, значения которого вычисляются как

          d = A->period_percent - B->period_percent

где A и B — записи из сравниваемого и базового файла, period_percent указывает процентную долю записи в одном файле данных. При фильтрации с использованием -C, -d и/или -S, значение period_percent может меняться в результате фильтрации. Предотвратить отклонения можно с помощью опции —percentage=absolute.

delta-abs

Работает как режим delta, но результаты сортируются по абсолютным значениям.

ratio

В этом режиме выводится столбец Ratio, значения которого вычисляются как

          r = A->period / B->period

где A и B — записи из сравниваемого и базового файла, period — значение периода в записи.

wdiff:WEIGHT-B,WEIGHT-A

В этом режиме выводится столбец Weighted diff, значения которого рассчитываются как

d = B->period * WEIGHT-A - A->period * WEIGHT-B

где A и B — записи из сравниваемого и базового файла, period — значение периода в записи, WEIGHT-A и WEIGHT-B — представленные пользователем веса в опции -c после разделителя вида -c wdiff:1,2.

cycles

В этом режиме выводится столбец [Program Block Range] Cycles Diff с разницей числа машинных тактов для одинаковых программных блоков в файлах. Базовым блоком программы считается код между двумя ветвлениями.

[Program Block Range] указывает диапазон базового программного блока. При доступности номеров строк выводятся эти номера, в остальных случаях — symbol+offset.

probe

Определяет новые динамические точки трассировки по символам и регистрам (без отладочной информации) или по выражениям C (номера строк, функции и локальные переменные C) при наличии отладочной информации.

Синтаксис

perf probe [options] --add=PROBE […]
perf probe [options] PROBE 
perf probe [options] --del=[GROUP:]EVENT [...] 
perf probe --list[=[GROUP:]EVENT] 
perf probe [options] --line=LINE 
perf probe [options] --vars=PROBEPOINT 
perf probe [options] --funcs 
perf probe [options] --definition=PROBE [...]

Опции

-k, —vmlinux=PATH

Задает путь к файлу vmlinux с отладочной информацией (dwarf). При использовании вместе с опцией —definition можно указать неактивный (offline) файл vmlinux.

-m, —module=MODNAME|PATH

Задает имя модуля, где perf probe будет искать точки или линии для зондов. Если путь пропущен, perf probe считает модуль неактивным (offline), это позволяет добавлять зонды в модуль, который еще не загружен.

-s, —source=PATH

Задает путь к исходным кодам ядра.

-v, —verbose

Подробный вывод (показ анализируемых аргументов и т. п.). Не может применяться вместе с опцией -q.

-q, —quiet

Сокращенный вывод (без показа каких-либо сообщений, включая ошибки). Не совместима с опцией -v.

-a, —add=

Определяет событие зонда (см. Синтаксис зондов).

-d, —del=

Удаляет события зондов. Могут применяться шаблоны glob (*, ?) и классы символов (например, [a-z], [!A-Z]).

-l, —list[=[GROUP:]EVENT]

Выводит список текущих событий зондов. Здесь можно указывать шаблоны фильтрации имен. При использовании с опцией —cache будут выводиться кэшированные зонды вместо активных.

-L, —line=

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

-V, —vars=

Показывает доступные локальные переменные точки зондирования. Синтаксис аргументом совпадает с описанным ниже, но без ARG.

—externs

Вывод определенных вовне переменных в дополнение к локальным (только для —vars).

—no-inlines

(только для —add) Поиск только функций, не являющихся встроенными (inline). Функции, не имеющие экземпляров, игнорируются.

-F, —funcs[=FILTER]

Показывать доступные функции данного модуля или ядра. При наличии опции -x или —exec могут также перечисляться функции в пользовательском пространстве исполняемого файла или общей библиотеки. Могут также применяться правила фильтрации (FILTER).

-D, —definition=

Показывать определение события трассировки, полученное из данного события зондирования, вместо записи в tracing/[k,u]probe_events.

—filter=FILTER

(только для —vars и —funcs) Задает фильтр (FILTER) из шаблонов glob (см. Шаблоны фильтров). По умолчанию применяется фильтр «!k???tab_* & !crc_*» для —vars и «!_*» для —funcs. При указании нескольких фильтров применяется последний.

-f, —force

Принудительно добавлять события с имеющимся именем.

-n, —dry-run

Холостой прогон. С этой опцией операции —add и —del не ведут к реальному добавлению или удалению.

—cache

Кэшировать зонды (с —add) — все добавленные события будут сохраняться в кэш-файле.

Показывать кэшированные зонды (с —list). Удалить кэшированные зонды (с —del).

—max-probes=NUM

Задает максимальное число точек отслеживания для события (по умолчанию 128).

—target-ns=PID

Получить информацию о пространстве имен монтирования от целевого pid. Это применяется при создании зонда для процесса размещенного в другом пространстве имен монтирования, нежели утилита perf.

-x, —exec=PATH

Задает путь к исполняемому файлу или общей библиотеке для трассировки в пользовательском пространстве. Может использоваться с опцией —funcs.

—demangle

Восстанавливать (demangle) символы приложения. Для отмены может использоваться опция —no-demangle.

—demangle-kernel

Восстанавливать (demangle) символы ядра. Для отмены может использоваться опция —no-demangle-kernel.

При отсутствии опций -m/-x команда perf probe проверяет первый аргумент после опций. Если это абсолютный путь, perf probe использует его в качестве цели для зонда пользовательского пространства или модуля.

Синтаксис зондов

Точки зондирования определяются с использованием показанного ниже синтаксиса.

По имени функции

[[GROUP:]EVENT=]FUNC[@SRC][:RLN|+OFFS|%return|;PTN] [ARG ...]

По файлу и номеру строки исходного кода
```
[[GROUP:]EVENT=]SRC:ALN [ARG ...]
```
По файлу исходного кода с шаблоном
```
[[GROUP:]EVENT=]SRC;PTN [ARG ...]
```
Предопределенные события SDT²³ или кэшированное событие с именем
```
%[sdt_PROVIDER:]SDTEVENT
```
или
```
sdt_PROVIDER:SDTEVENT
```

Поле EVENT указывает имя нового события и при отсутствии поля будет использовано имя пробной функции, а к возвращаемым пробам автоматически будет добавляться суффикс __return. Можно указать имя группы в поле GROUP, а при его отсутствии будет использоваться установленное имя зонда для kprobe и probe_<bin> — для uprobe. Отметим, что при использовании имени существующей группы могут возникать конфликты с другими событиями. В частности, использование имени группы, зарезервированного для модулей ядра, может скрывать встроенные события в модулях. FUNC указывает имя зондируемой функции и может принимать одну из форм: +OFFS указывает смещение от точки входа в функцию в байтах, :RLN указывает номер строки относительно входной строки функции, %return означает зондирование возврата из функции, а ;PTN задает шаблон сопоставления (см. Сопоставление с шаблоном). Отметим, что ;PTN должно помещаться в конце определения точки зондирования. Необязательное поле @SRC указывает файл с исходным кодом, где размещена эта функция. Можно также указать точку зондирования номером строки или шаблоном сопоставления, используя синтаксис SRC:ALN или SRC;PTN, где SRC задает путь к файлу с исходным кодом, :ALN — номер строки, а ;PTN — шаблон сопоставления. ARG задает аргументы точки зондирования (см. Аргументы зонда). SDTEVENT и PROVIDER указывают предопределенное имя события, которое задано пользовательским SDT или кэшированными ранее зондами с именем события. Отметим, что перед использованием события SDT нужно просканировать целевой двоичный файл (где определены события SDT) с помощью perf buildid-cache, чтобы добавить события SDT в кэш.

ESCAPE-символы

С синтаксисе probe символы =, @, +, : и ; имеют специальное значение. Для блокирования специальной трактовки следует использовать перед ними escape-символ \. Это полезно при зондировании символов определенной версии (например, @GLIBC_) или для указания файлов исходного кода с такими символами в имени. Отметим, что символ \ имеет специальное значение в командных процессорах и может потребоваться два таких символа (\\) или использование кавычек ‘AAA\@BBB’ (см. Примеры).

Аргументы зонда

Каждый аргумент зонда использует приведенный ниже синтаксис

[NAME=]LOCALVAR|$retval|%REG|@SYMBOL[:TYPE]

NAME задает (необязательное) имя аргумента. Можно использовать имя локальной переменной, элемента локальной структуры (например, var→field, var.field2), локальный массив с фиксированным индексом (например, array[1], var→array[0], var→pointer[2]), или формат аргументов трассировщика kprobe (например, $retval, %ax). Отметим, что имя аргумента будет указано в качестве имени последнего элемента, если вы зададите элемент локальной структуры данных (например. field2 для var→field1.field2.) Специальные аргументы $vars и $params также могут применяться для NAME, при этом $vars преобразуется в локальные переменные (включая параметры функции), которые могут быть доступны в данной точке зондирования, $params преобразуется только в параметры функции. TYPE служит для приведения типа аргумента (необязательно) и при отсутствии его perf probe автоматически задает тип на основе debuginfo. В настоящее время поддерживаются базовые типы (u8/u16/u32/u64/s8/s16/s32/s64), шестнадцатеричные целые числа (x/x8/x16/x32/x64), приведение к знаку (u/s), string и bitfield (см. Типы). В системах x86 запись %REG всегда означает краткую форму регистра, например, %AX (%RAX или %EAX недействительны).

Типы

Базовые типы (u8/u16/u32/u64/s8/s16/s32/s64) и шестнадцатеричные целые (x8/x16/x32/x64) являются целочисленными типами. Префиксы s и u задают наличие (signed) и отсутствие (unsigned) знака, а x указывает шестнадцатеричный формат. Отслеживаемые аргументы задаются в десятичной (sNN/uNN) или шестнадцатеричной (xNN) форме. Можно использовать префиксы s или u для указания знака, а можно опускать префикс, позволяя perf probe определить его автоматически. Префикс x можно использовать для явного указания шестнадцатеричных чисел (размер определяется автоматически). Тип string служит для завершаемых null-символом строк из пространства ядра. Это означает отказ или сохранение значения NULL, если контейнер строки переходит через границу страницы. Можно указывать тип string лишь для локальной переменной или элемента структуры, который является массивом или указателем на тип char или unsigned char. Другой специальный тип bitfield принимает 3 параметра — размер (bit-width), смещение (bit-offset) и размер контейнера (container-size, обычно 32). Синтаксис имеет вид

b<bit-width>@<bit-offset>/<container-size>

Синтаксис строк

Диапазон строк описывается приведенным ниже синтаксисом.

"FUNC[@SRC][:RLN[+NUM|-RLN2]]|SRC[:ALN[+NUM|-ALN2]]"

FUNC задает имя функции для показанных строк. RLN указывает номер первой строки от точки входа в функцию, RLN2 — номер последней строки. Как и для синтаксиса проб SRC указывает путь к файлу исходного кода, ALN — номер стартовой строки, ALN2 — номер последней строки в файле. Можно также задать число выводимых строк параметром NUM. Кроме того, комбинация FUNC@SRC удобна для поиска конкретной функции среди нескольких одноименных. Так «source.c:100-120» показывает строки с 100-й по l20-ю в файле source.c, а «func:10+20» — 20 строк, начиная с 10-й, для функции func.

Сопоставление с шаблоном

«Ленивое» сопоставление строк похоже на сопоставление glob, но игнорирует пробелы в обоих сравниваемых частях. Для сопоставления можно применять символы-шаблоны (*, ?) и классы символов (например, [a-z], [!A-Z]). Например, выражению a=* будут соответствовать a=b, a = b, a == b и т. п..

Это обеспечивает некоторую гибкость и отказоустойчивость определений точек зондирования к незначительному изменению кода. Например, 10-я строка schedule() может быть перемещена при изменении schedule(), но строка, соответствующая rq=cpu_rq*, может сохраниться в функции.

Шаблоны фильтров

Шаблон фильтра — это выражения glob для сопоставления с переменными фильтра. В дополнение можно использовать символ ! Для обращения правила. Можно задать несколько правил, объединенных операциями & (и) и | (или), и «свернуть» эти правила в одно с помощью скобок. Например с —filter «foo* | bar*», команда perf probe -V покажет переменные, начинающиеся с foo или bar. С фильтром —filter «!foo* & *bar» команда perf probe -V покажет переменные, которые начинаются не с foo и заканчиваются на bar, такие как fizzbar. Но foobar будет отфильтрована.

Примеры

Вывод строк в schedule(), которые могут быть прозондированы

          ./perf probe --line schedule

Добавление зонда в 12-ю строку функции schedule() function с записью локальной переменной cpu

          ./perf probe schedule:12 cpu

или

          ./perf probe --add='schedule:12 cpu'

Добавление одного или нескольких зондов, имена которых начинаются с schedule

          ./perf probe schedule*

или

          ./perf probe --add='schedule*'

Добавление зондов в строки функции schedule(), вызывающие update_rq_clock()

          ./perf probe 'schedule;update_rq_clock*'

или

          ./perf probe --add='schedule;update_rq_clock*'

Удаление всех зондов из schedule()

          ./perf probe --del='schedule*'

Добавление зондов в функцию zfree() командного процессора /bin/zsh

          ./perf probe -x /bin/zsh zfree or ./perf probe /bin/zsh zfree

Добавление зондов в функцию malloc() библиотеки libc

          ./perf probe -x /lib/libc.so.6 malloc or ./perf probe /lib/libc.so.6 malloc

Добавление uprobe в целевой процесс, работающий в другом пространстве имен (монтирования)

          ./perf probe --target-ns <target pid> -x /lib64/libc.so.6 malloc

Добавление зонда USDT в целевой процесс, работающий в другом пространстве имен (монтирования)

./perf probe --target-ns <target pid> -x /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.121-0.b13.el7_3.x86_64/jre/lib/amd64/server/libjvm.so %sdt_hotspot:thread__sleep__end

Добавление зонда в символ конкретной версии с использованием escape

          ./perf probe -x /lib64/libc-2.25.so 'malloc_get_state\@GLIBC_2.2.5'

Добавление зонда в файл исходного кода с использованием escape-символа

          ./perf probe -x /opt/test/a.out 'foo\+bar.c:4'

inject

Фильтр для добавления информации в поток событий. Команда perf inject читает поток событий perf record и передает его в stdout. В любой точке код обработки может вставить в поток другие события — в этом случае считываются идентификаторы сборки (опция -b) и помещаются в поток событий.

Идентификаторы сборки являются лишь первым примером использования perf inject, на деле в поток можно добавить все, что требует обработки в пользовательском пространстве, для дополнения потока событий информацией.

Синтаксис

perf inject <options>

Опции

-b, —build-ids=

Помещает идентификаторы сборки в поток событий.

-v, —verbose

Подробный вывод.

-i, —input=

Имя входного файла (по умолчанию stdin).

-o, —output=

Имя выходного файла (по умолчанию stdout).

-s, —sched-stat

Объединяет sched_stat и sched_switch для получения событий о точках (цепочка вызовов) и продолжительности сна задачи.

—kallsyms=<file>

путь к файлу kallsyms.

—itrace

Задает опции декодирования данных трассировки инструкций, заменяемые синтезированными событиями:

i синтезировать события инструкций;

b синтезировать события ветвления;

c синтезировать события ветвления (только вызовы);

r синтезировать события ветвления (только возвраты);

x синтезировать события транзакций;

w синтезировать события ptwrite;

p синтезировать события, связанные с питанием;

e синтезировать события, связанные с ошибками;

d создать журнал отладки;

g синтезировать цепочку вызовов (используется с i или x);

l синтезировать записи последнего ветвления (используется с i или x);

s пропустить указанное число записей в начале.

По умолчанию учитываются все события (—itrace=ibxwpe), за исключением perf (—itrace=ce)

i инструкции;

t такты часов;

ms миллисекунды;

us микросекунды;

ns наносекунды (используется по умолчанию).

Можно также указать размер цепочки (по умолчанию 16, максимум 1024) для событий.

Можно указать также число записей последнего ветвления (по умолчанию 64, максимум 1024).

              --itrace=i0nss1000000

обеспечит пропуск первого миллиона инструкций.

—strip

используется с —itrace для удаления несинтезированных событий.

-j, —jit

Обрабатывать файлы jitdump путем вставки записей mmap, соответствующих jit²⁴-функциям. Эта опция также генерирует образы ELF для каждой jit-функции в файлах jitdump, собранных во входном файле perf.data. Опцию следует применять при мониторинге среды, использующей JIT-приложения, такие как Java, DART, V8.

-f, —force

Выполнять без лишних вопросов.

data

Преобразование формата файла данных.
Синтаксис

perf data [<common options>] <command> [<options>]

Команды

convert

Преобразует файл perf.data в другой формат (в настоящее время поддерживается лишь формат CTF [1]). Можно установить переменную —debug для получения отладочных сообщений в процессе преобразования (perf —debug data …).

Опции преобразования

—to-ctf

Задает преобразование в формат CTF и путь к каталогу данных CTF.

-i

Задает путь к входному файлу данных perf.

-f, —force

Форсирует преобразование без лишних вопросов.

-v, —verbose

Задает подробный вывод (ошибки открытия счетчиков и т. п.).

—all

Преобразовывать все события, включая не связанные с выборкой (comm, fork, …). По умолчанию выключено и преобразуются лишь выборки.

list

Выводит список символьных имен событий, которые могут выбираться в командах perf с опцией -e.

Синтаксис

perf list [--no-desc] [--long-desc] [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]

Опции

-d, —desc

Выводить дополнительные описания событий (принято по умолчанию).

—no-desc

Не выводить описания событий.

-v, —long-desc

Выводить более подробные описания.

—debug

Включить отладочный вывод.

—details

Выводит информацию о преобразовании именованных событий в события perf, а также дополнительные выражения, рассчитываемые perf stat.

Модификаторы событий

События могут включать модификаторы, добавленные через двоеточие. Модификаторы позволяют ограничить учитываемые события. Доступные модификаторы перечислены ниже.

u учет для пользовательского пространства;

k учет для ядра;

h учет для гипервизора;

I учет действующих (не idle) событий;

G учет гостевых событий в KVM;

H учет событий хоста (не KVM);

p точный уровень;

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

S считывать значение в выборке (PERF_SAMPLE_READ);

D прикрепить событие к PMU;

W группа задана слабо и при отсутствии планирования не используется.

Модификатор p может применяться для указания степени точности адреса инструкции и может указываться несколько раз:

0 SAMPLE_IP может иметь произвольный идентификатор skid;

1 SAMPLE_IP должен иметь постоянный идентификатор skid;

2 для SAMPLE_IP запрошен skid 0;

3 SAMPLE_IP должен иметь skid 0 или быть случайным для предотвращения эффектов «затемнения».

Для систем Intel точная выборка событий реализуется с помощью PEBS²⁵, поддерживающей уровни 0-2, а в особых случаях и 3.

В системах AMD это реализовано с помощью IBS²⁶ (до уровня 2). Модификатор precise работает с событиями типов 0x76 (cpu-cycles, часы CPU не остановлены) и 0xC1 (микрооперации скрыты). Оба события отображаются на выборку IBS (IBS op) с соответственно установленным битом IBS Op Counter Control (IbsOpCntCtl) [2]. Примеры использования IBS приведены ниже.

          perf record -a -e cpu-cycles:p ...    # use ibs op counting cycles 
          perf record -a -e r076:p ...          # same as -e cpu-cycles:p 
          perf record -a -e r0C1:p ...          # use ibs op counting micro-ops

Дескриптор необработанного аппаратного события

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

Например, для процессоров x86 NNN представляет кодирование по схеме IA32_PERFEVTSELx MSR (см. Figure 30-1 Layout of IA32_PERFEVTSELx MSRs в [3]) или AMD PerfEvtSeln (см. Figure 13-7 Performance Event-Select Register (PerfEvtSeln) в [2], стр. 344).

Примечание. В регистрах счетчиков x86 можно установить только поля event, umask, edge, inv, cmask. В частности, флаги режимов guest/host и OS/user должны устанавливаться только с помощью модификаторов событий (см. выше).

Например, если в документации Intel для QM720 Core i7 событие описано как показано ниже.

          Event  Umask  Event Mask 
          Num.   Value  Mnemonic    Description                        Comment 

          A8H      01H  LSD.UOPS    Counts the number of micro-ops     Use cmask=1 and 
                                    delivered by loop stream detector  invert to count 
                                                                       cycles

Можно использовать необработанное кодирование в форме

          perf stat -e r1a8 -a sleep 1 
          perf record -e r1a8 ...

Для получения информации следует обращаться к документации используемого процессора.

Произвольные PMU

Программа perf поддерживает расширенный синтаксис для задания необработанных параметров PMU. Для работы с ним обычно требуется разбираться с конкретным событием по документации производителя CPU.

Список доступных PMU и их необработанных параметров можно получить с помощью команды

          ls /sys/devices/*/format

Например, событие LSD.UOPS можно указать в форме

          perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...

или с использованием расширенного синтаксиса

perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...

PMU на уровне сокета

Некоторые PMU связаны не с ядрами, а с сокетом CPU в целом. События в таких PMU в общем случае невозможно выбрать и можно лишь учитывать глобально по команде perf stat -a. Они могут быть связаны с одним логическим CPU, но будут измеряться на всех ядрах одного сокета.

Приведенная ниже команда измеряет пропускную способность памяти каждую секунду на первом контроллере сокета 0 в системе Intel Xeon

perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...

Каждый контроллер памяти имеет свой блок PMU. Измерение полной пропускной способности в системе потребует указания всех imc PMU (см. вывод perf list) и сложения полученных значений. Для упрощения создания множества событий, префиксов и шаблонов имен PMU подстроки uncore_ игнорируются при сопоставлении. Поэтому приведенную выше команду можно распространить на все контроллеры, используя показанный ниже синтаксис

          perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ... 
          perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...

Приведенный ниже пример служит для измерения суммарной потребляемой энергии каждую секунду

          perf stat -I 1000 -e power/energy-cores/ -a

Ограничение доступа

Обычным пользователям (не root) обычно доступны лишь события PMU для переключения контекста. Это обычно лишь предопределенные события в PMU, такие как циклы, инструкции и некоторые программные события.

Другие PMU и глобальные измерения обычно доступны лишь пользователю root. Некоторые классификаторы событий (такие как any) тоже доступны только для root.

Это поведение можно изменить путем установки для переменной sysctl kernel.perf_event_paranoid значения -1, позволяющего обычным пользователям видеть такие события.

Для доступа к событиям точек трассировки программе perf нужно читать каталог /sys/kernel/debug/tracing даже при смягченной установке perf_event_paranoid.

Аппаратная трассировка

Некоторые PMU контролируют расширенные возможности аппаратной трассировки (такие как Intel PT), что позволяет выполнять трассировку с меньшими издержками. Описание Intel PT приведено в отдельном документе intel-pt.txt.

Параметризованные события

Некоторые события PMU, сообщаемые по команде perf list, будут указаны со знаком вопроса (?). Например,

          hv_gpci/dtbp_ptitc,phys_processor_idx=?/

Это означает, что предоставление этого события должно сопровождаться представлением значения для ?. Например,

          perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...

Классификаторы событий

Можно также добавлять к событиям классификаторы. Например

percore:

Для суммирования счетчиков событий во всех аппаратных потоках ядра можно ввести команду

          perf stat -e cpu/event=0,umask=0x3,percore=1/

Группы событий

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

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

          perf stat -e '{instructions,cycles}' ...

Число доступных счетчиков производительности зависит от CPU. Число событий в группе не может быть больше числа доступных счетчиков. Например, Intel Core CPU обычно включают 4 базовых счетчика на ядро и 3 фиксированных счетчика для инструкций, циклов и опорных циклов (ref-cycle). Для некоторых событий имеются ограничений на планируемые счетчики и они могут не поддерживаться в нескольких экземплярах для группы. При включении в группу слишком большого числа событий некоторые из них не будут учитываться.

Глобально прикрепленные события могут ограничивать число счетчиков, доступных для других групп. В системах x86 по умолчанию NMI watchdog имеет прикрепленный счетчик. Это можно отключить командой

          echo 0 > /proc/sys/kernel/nmi_watchdog

События из разных PMU нельзя смешивать в одну группу, однако для программных событий имеется ряд исключений.

Лидер выборки

Программа perf поддерживает указание лидера групповой выборки с помощью спецификатора :S.

          perf record -e '{cycles,instructions}:S' ... 
          perf report --group

Обычно отбираются все события группы, но при использовании :S выборка делается только для первого (лидер), а для остальных лишь считываются значения.

Опции

Без указания опций будут выведены все известные события. Для ограничения списка можно применять перечисленные ниже опции.

hw или hardware для вывода списка аппаратных событий (например, cache-misse).
sw или software для вывода списка программных событий, таких как переключение контекста.
cache или hwcache для вывода событий аппаратного кэширования (например, L1-dcache-load).
tracepoint для списка всех событий трассировки. Альтернативой служит subsys_glob:event_glob для фильтрации по подсистемам трассировки, таким как sched, block и т. п..
pmu для вывода списка предоставляемых ядром событий PMU.
sdt для вывода всех событий SDT.
metric для списка параметров метрики.
metricgroup для списка групп параметров метрики.
Если не подходит ничего из перечисленного выше, можно воспользоваться регулярным выражением (glob) для поиска совпадений в списке всех событий.
Можно также применить поиск подстроки в именах всех событий.

Можно указать несколько типов сразу (через пробелы) для вывода соответствующих списков.

Для необработанных форматов служит опция —raw-dump:

—raw-dump показывает raw-dump для всех событий;
—raw-dump [hw|sw|cache|tracepoint|pmu|event_glob] показывает raw-dump заданного типа событий.

evlist

Вывод списка событий из файла perf.data.

Синтаксис

perf evlist <options>

Опции

-i, —input=

Имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-f, —force

Форсированные выполнение без лишних вопросов.

-F, —freq=

Показать просто частоту выборки, использованную для каждого события.

-v, —verbose=

Показывать все поля.

-g, —group

Показывать информацию о группах событий.

—trace-fields

Показывать имена полей точек трассировки.

buildid-list

Выводит список идентификаторов сборки (build-id), найденных в файле perf.data, которые позволяют использовать другие инструменты для извлечения пакетов с соответствующими таблицами символов при создании отчетов с помощью perf report.

Команда также может служить для вывода идентификаторов сборки работающего ядра или файла ELF (-i/—input).

Синтаксис

perf buildid-list <options>

Опции

-H, —with-hits

Показывать только затронутые DSO.

-i, —input=

Имя входного файла (по умолчанию perf.data, если stdin не является fifo).

-f, —force

Не проверять владельцев.

-k, —kernel

Показывать идентификатор сборки работающего ядра.

-v, —verbose

Подробный вывод

buildid-cache

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

Команда также сканирует целевой двоичный файл на предмет точек SDT и записывает их вместе с кэшем идентификаторов сборки для последующего использования командой perf probe.

Синтаксис

perf buildid-cache <options>

Опции

-a, —add=

Добавляет указанный файл в кэш.

-f, —force

Выполнять без дополнительных вопросов.

-k, —kcore

Добавляет в кэш указанный файл kcore. Для текущего хоста это файл /proc/kcore, для чтения которого нужны полномочия root. Запуск buildid-cache от имени root может обновлять кэш идентификаторов сборки root, а не пользователя. Для просмотра точки создания файла служит опция -v. Отметим, что скопированный файл содержит только секции кода, а не весь образ. Файлы kallsyms и modules должны быть в том же каталоге и тоже копироваться. Все 3 файла создаются с правом чтения только для root. Файл kcore не будет добавлен, если kcore уже есть у кэше (с тем же build-id) и имеет те же модули с теми же адресами. Проверить актуальность kcore можно с помощью опции -v.

-r, —remove=

Удаляет из кэша двоичный файл с тем же build-id.

-p, —purge=

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

-P, —purge-all

Очищает все кэшированные двоичные файлы, полностью сбрасывая кэш.

-M, —missing=

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

-u, —update=

Обновляет указанный файл в кэше. Старые записи не удаляются, поскольку они еще могут быть нужны для аннотирования старых (или удаленных) файлов perf.data. Заменяется лишь кэшированный файл с тем же идентификатором сборки. Это может применяться для обновления kallsyms и dso ядра до уровня vmlinux с целью поддержки аннотирования.

-l, —list

Список всех действительных двоичных файлов в кэше.

-v, —verbose

Подробный вывод.

—target-ns=PID

kallsyms

Ищет символы для работающего ядра. Просматривается файл kallsyms и выводится информация о найденных символах, включая DSO, начальный и конечный адрес kallsyms и адреса в таблице символов ELF kallsyms (для символов в модулях).

Синтаксис

perf kallsyms [<options>] symbol_name[,symbol_name...]

Опции

-v, —verbose=

Расширенный вывод с показом деталей загрузки таблицы символов и т. п.

config

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

Синтаксис

perf config [<file-option>] [section.name[=value] ...] 
perf config [<file-option>] -l | --list

Опции

-l, —list

Показывает текущие переменные (имена и значения) из всех разделов конфигурационного файла.

—user

Задает имя пользователя для работы с опциями в файле $HOME/.perfconfig.

—system

Служит для работы с системным файлом конфигурации $(sysconfdir)/perfconfig.

Конфигурационный файл

Конфигурационный файл perf содержит множество переменных для управления различными аспектами работы инструментов, включая вывод, использование дисков и т. п. Файлы $HOME/.perfconfig служат для управления конфигурацией отдельных пользователей, а файл $(sysconfdir)/perfconfig служит для задания общих параметров. В современных системах конфигурационных файлов perf может просто не присутствовать, поскольку используемые по умолчанию значения переменных заданы непосредственно в программе. В этом случае вывод команды perf config -l будет пустым.

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

Синтаксис

Конфигурационный файл содержит множество разделов. Каждый раздел начинается именем, указанным в квадратных скобках и продолжается до начала следующего раздела. Каждая переменная должна быть в одном из разделов и задается в форме name = value. Например,

          [section] 
                  name1 = value1 
                  name2 = value2

Регистр символов в именах разделов учитывается, а имена могут включать любые символы кроме перевода строки. Для символов двойных кавычек и обратной дробной черты применяются escape-последовательности \» и \\. Имя раздела не может включать несколько строк.

Пример

Ниже приведен пример пользовательского файла $HOME/.perfconfig.

      # # Это пользовательский конфигурационный файл. # и #; указывают комментарии.

          [colors] 
                  # Color variables 
                  top = red, default 
                  medium = green, default
                  normal = lightgray, default 
                  selected = white, lightgray 
                  jump_arrows = blue, default 
                  addr = magenta, default 
                  root = white, blue 

          [tui] 
                  # Defaults if linked with libslang 
                  report = on 
                  annotate = on 
                  top = on 

          [buildid] 
                  # Default, disable using /dev/null 
                  dir = ~/.debug 

          [annotate] 
                  # Defaults 
                  hide_src_code = false 
                  use_offset = true 
                  jump_arrows = true 
                  show_nr_jumps = false 

          [help] 
                  # Format can be man, info, web or html 
                  format = man 
                  autocorrect = 0 

          [ui] 
                  show-headers = true 

          [call-graph] 
                  # fp (framepointer), dwarf 
                  record-mode = fp 
                  print-type = graph 
                  order = caller 
                  sort-key = function 

          [report] 
                  # Defaults 
                  sort_order = comm,dso,symbol 
                  percent-limit = 0 
                  queue-size = 0 
                  children = true 
                  group = true 

          [llvm] 
                  dump-obj = true 
                  clang-opt = -g

Можно скрыть исходный код при аннотировании с помощью команды

          % perf config annotate.hide_src_code=true

Для добавления или изменения нескольких элементов конфигурации можно воспользоваться командой вида

          % perf config ui.show-headers=false kmem.default=slab

Для изменения порядка сортировки функций отчета в пользовательском файле (~/.perfconfig) служит команда

          % perf config --user report sort-order=srcline

Для изменения цвета выбранной строки с системном конфигурационной файле ($(sysconf)/perfconfig) служит команда

          % perf config --system colors.selected=yellow,green

Для запроса режима графа вызовов служит команда

          % perf config call-graph.record-mode

Для считывания нескольких пар «ключ-значение» можно использовать команду вида

          % perf config report.queue-size call-graph.order report.children

Для считывания порядка сортировки из пользовательского файла (~/.perfconfig), служит команда

          % perf config --user call-graph.sort-order

Для запроса каталога с идентификаторами сборки в системном файле ($(sysconf)/perfconfig) служит команда

          % perf config --system buildid.dir

Переменные

colors.*

Переменные для управления цветом при выводе команд report, top и annotate в интерфейсе TUI. Следует указывать цвет символов и фона через запятую. Например,

              medium = green, lightgray

Если нужно использовать цвета, настроенные для терминала, просто указывается значение default. Например,

              medium = default, lightgray

Доступны цвета red, yellow, green, cyan, gray, black, blue, white, default, magenta, lightgray.

colors.top

Переменная top задает цвет для издержек, превышающих 5%. Базовым является красный цвет на обычном фоне.

colors.medium

Переменная medium задает цвет для издержек, превышающих 0,5% (по умолчанию зеленый на обычном фоне).

colors.normal

Переменная normal задает цвет для издержек, не относящихся к top, medium, selected (по умолчанию светло-серый на обычно фоне).

colors.selected

Переменная selected задает цвет и фон текущей записи в списке записей субкоманд (top, report, annotate). По умолчанию черный цвет на светло-сером фоне.

colors.jump_arrows

Цвета для стрелок перехода в ассемблерном коде, таких как jns, jmp, jane и т. п. По умолчанию голубой на обычном фоне.

colors.addr

Цвета для адресов в аннотации. По умолчанию пурпурный на обычном фоне.

colors.root

Цвета для заголовков в выводе субкоманд (top, report). По умолчанию белый на синем фоне.

core.*, core.proc-map-timeout

Задает тайм-аут (в миллисекундах, по умолчанию 500) при разборе файлов /proc/<pid>/maps. Может быть переопределен опциями —proc-map-timeout в поддерживаемых субкомандах.

tui., gtk.

Субкоманды, которые могут быть настроены (top, report и annotate). Например,

              [tui] 
                      top = true

будет включать в TUI по умолчанию команду top. Команда будет доступна при наличии требуемых библиотек в момент сборки perf.

buildid.*, buildid.dir

Каждый исполняемый файл и библиотека общего пользования в современных дистрибутивах имеет идентификатор содержимого, который (при доступности) помещается в заголовок файла perf.data, чтобы во время анализа можно было найти информацию для преобразования символов, аннотирования кода и т. п.

Инструменты записи сохраняют ссылку или копию двоичных файлов, общих библиотек, файлов /proc/kallsyms и /proc/kcore в пользовательском файле $HOME/.debug/ для использования при анализе.

Переменная buildid.dir может применяться для изменения каталога кэширования или запрета такого кэширования (buildid.dir = /dev/null). По умолчанию используется каталог $HOME/.debug

annotate.*

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

annotate.hide_src_code

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

              │        push   %rbp 
              │        mov    %rsp,%rbp 
              │        sub    $0x10,%rsp 
              │        mov    (%rdi),%rdx

Но при выключенной (false) опции будет выводиться также исходный код (применяется по умолчанию).

              │      struct rb_node *rb_next(const struct rb_node *node) 
              │      { 
              │        push   %rbp 
              │        mov    %rsp,%rbp 
              │        sub    $0x10,%rsp 
              │              struct rb_node *parent; 
              │ 
              │              if (RB_EMPTY_NODE(node)) 
              │        mov    (%rdi),%rdx 
              │              return n;

annotate.use_offset

Можно использовать смещение от первого адреса загруженной функции. Вместо применения исходных адресов ассемблерного кода указывается разница с базовым адресом. Рассмотрим это на примере. Если базовый адрес имеет значение 0XFFFFFFFF81624d50, как показано ниже

              ffffffff81624d50 <load0>

и ассемблерный код имеет абсолютный адрес

              ffffffff816250b8:│  mov    0x8(%r14),%rdi

то при use_offset = true выводится разница с базовым адресом (принято по умолчанию). Опция применима лишь в TUI.

              368:│  mov    0x8(%r14),%rdi

annotate.jump_arrows

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

              │     ┌──jmp    1333 
              │     │  xchg   %ax,%ax 
              │1330:│  mov    %r15,%r10 
              │1333:└─→cmp    %r15,%r14

Если jump_arrow = false, переход не будет показан (принято по умолчанию).

              │      ↓ jmp    1333 
              │        xchg   %ax,%ax 
              │1330:   mov    %r15,%r10 
              │1333:   cmp    %r15,%r14

annotate.show_linenr

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

              │1628         if (type & PERF_SAMPLE_IDENTIFIER) { 
              │     ↓ jne    508 
              │1628                 data->id = *array; 
              │1629                 array++; 
              │1630         }

Если опция имеет значение false (принято по умолчанию), номера строк не выводятся.

              │             if (type & PERF_SAMPLE_IDENTIFIER) { 
              │     ↓ jne    508 
              │                     data->id = *array; 
              │                     array++; 
              │             }

annotate.show_nr_jumps

Позволяет выводить часть ассемблерного кода.

              │1382:   movb   $0x1,-0x270(%rbp)

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

              │1 1382:   movb   $0x1,-0x270(%rbp)

annotate.show_total_period

Эта переменная управляет выводом числа выборок, относящихся к строке ассемблерного кода. Если переменная имеет значение true, выводятся суммарные периоды вместо процентных значений.

              302 │      mov    %eax,%eax

Но при значении false (принято по умолчанию) выводится процент издержек.

              99.93 │      mov    %eax,%eax

annotate.offset_level

По умолчанию установлено значение 1, при котором выводится смещение цели перехода справа от инструкции. При значении 2 будут также показаны смещения для инструкций вызова, а при значениях 3 и больше выводятся смещения для всех инструкций.

hist.*, hist.percentage

Эта переменная управляет способом расчета издержек отфильтрованных записей и принимается во внимание только при наличии фильтра (comm, dso или имя символа). Рассмотрим пример

              Overhead  Symbols 
              ........  ....... 
               33.33%     foo
               33.33%     bar 
               33.33%     baz

Здесь показаны исходные издержки и если отфильтровать первую запись foo, то при значении данной переменной relative издержки bar и baz примут значения 50.00%, а при значении absolute сохранится текущее значение 33.33%.

ui.*, ui.show-headers

Эта переменная управляет выводом столбцов (например, Overhead и Symbol) для команд report и top в интерфейсе TUI. При значении false имена столбцов не выводятся.

call-graph.*

Для команд top и report с опцией -g/—children эти переменные управляют графом вызовов.

call-graph.record-mode

Для команды record может быть выбран режим fp (указатель кадра), dwarf или lbr. Значение dwarf работает только при обнаружении программой perf нужной библиотеки (libunwind или свежая версия libdw). Режим lbr работает только для поддерживающих его процессоров.

call-graph.dump-size

Размер стека для дампа (по умолчанию 8192 байта). В режиме записи dwarf используется принятое по умолчанию значение, если размер не указан.

call-graph.print-type

Задает тип вывод graph (абсолютный граф), fractal (относительный граф), flat (плоский) или folded (свертка). Эта переменная управляет выводом значений издержек для каждой записи цепочки вызовов. Рассмотрим пример

              Overhead  Symbols 
              ........  ....... 
                40.00%  foo 
                        | 
                        ---foo 
                           | 
                           |--50.00%--bar 
                           |          main 
                           | 
                            --50.00%--baz 
                                      main

Здесь используется формат fractal. Вызов foo делится поровну между bar и baz, поэтому показаны значения 50.00% для каждого (100% общих издержек foo). В режиме graph указываются абсолютные издержки foo, поэтому для bar и baz будут показаны значения 20.00%. В режиме flat выводится одна строка с линейным представлением цепочек вызовов. В режиме folded цепочки вызовов выводятся в одну строку через точку с запятой (;).

call-graph.order

Управляет порядков вывода цепочек вызовов. По умолчанию используется режим callee, где сверху указывается вызываемая функция, а далее — вызывающие в обратном порядке.

Если эта опция не установлена, а для report.children или top.children задано значение true (или эквивалентная опция в командной строке), применяется режим caller для команд perf report и perf top. Для остальных команд по умолчанию используется режим callee.

call-graph.sort-key

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

call-graph.threshold

При наличии множества цепочек вызовов вывод будет очень большим. Поэтому perf опускает мелкие цепочки с издержками ниже заданного этой переменной порога (по умолчанию 0.5 %). Расчет издержек зависит от значения переменной call-graph.print-type.

call-graph.print-limit

Максимальное число строк цепочки вызовов для одного элемента гистограммы. По умолчанию число не ограничено (0).

report.*, report.sort_order

Позволяет сменить принятый по умолчанию порядок сортировки comm,dso,symbol на другой, например, sym,dso.

report.percent-limit

Похожа на call-graph.threshold, но применяется для элементов гистограммы. По умолчанию установлен порог 0. При percent-limit = 10 будут выводиться лишь записи с издержками более 10%.

report.queue-size

Задает максимальный размер для внутренней очереди событий (по умолчанию не ограничен — 0).

report.children

При значении этой переменной true (принято по умолчанию) команда perf report собирает цепочки вызовов дочерних функций и показывает их общие издержки вместе с издержками родительской функции (Self).

report.group

Задает совместный вывод информации для группы событий. Ниже приведен пример вывода со включенной опцией, где указывается один столбец на группу.

              # group: {ref-cycles,cycles} 
              # ======== 
              # 
              # Samples: 7K of event 'anon group { ref-cycles, cycles }' 
              # Event count (approx.): 6876107743 
              # 
              #         Overhead  Command      Shared Object               Symbol 
              # ................  .......  .................  ................... 
              # 
                  99.84%  99.76%  noploop  noploop            [.] main 
                   0.07%   0.00%  noploop  ld-2.15.so         [.] strcmp 
                   0.03%   0.00%  noploop  [kernel.kallsyms]  [k] timerqueue_del

top.*, top.children

То же, что report.children. При включенной опции вывод команды top включает столбец издержек Children, а также Self (по умолчанию true).

man.*, man.viewer

Эта опция может задавать программу для просмотра страниц руководства по команде help. Поддерживаются программы man, woman (с клиентом emacs) и konqueror. По умолчанию применяется man.

Новую программу просмотра руководств можно также задать с помощью man.<tool>.cmd или man.<tool>.path.

pager.*, pager.<subcommand>

Для интерфейса stdio определяет программу разбиения на страницы (pager). По умолчанию не задана.

kmem.*, kmem.default

Задает средство распределения, используемое при анализе, если не задана ни одна из опций —slab и —page. По умолчанию принимается slab.

record.*, record.build-id

Эта переменная может принимать значение cache, no-cache или skip. Вариант cache служит для постобработки данных и сохранения/обновления двоичной информации в кэше идентификаторов сборки (~/.debug). Этот вариант применяется по умолчанию. При выборе no-cache кэш идентификаторов сборки не обновляется, а при выборе skip не выполняется постобработки и не обновляется кэш.

diff.*, diff.order

Задает номер столбца для сортировки результатов. Установленное по умолчанию значение 0 обеспечивает сортировку по базовой линии, при значении 1 сортировка будет выполняться по приращению (или другому выбранному методу расчета).

diff.compute

Задает метод определения различий и может принимать значения delta (по умолчанию), delta-abs, ratio и wdiff.

trace.*, trace.add_events

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

trace.args_alignment

Число столбцов (терминала) для размещения аргументов (по умолчанию 70). Для strace по умолчанию используется 40. 0 отменяет выравнивание.

trace.no_inherit

Не следовать за дочерними потоками.

trace.show_arg_names

Управляет выводом имен аргументов syscall. При отключенном выводе будет установлено trace.show_zeros.

trace.show_duration

Показывать продолжительность syscall.

trace.show_prefix

При установке значения yes будут показаны базовые префиксы строк в таблицах. По умолчанию базовые префиксы удаляются. Например, вместо MAP_SHARED будет выведено SHARED.

trace.show_timestamp

Показывать стартовую временную метку syscall.

trace.show_zeros

Не подавлять аргументы syscall со значением 0.

llvm.*, llvm.clang-path

Путь к clang. Если путь не указан, выполняется поиск по значению переменной окружения $PATH.

llvm.clang-bpf-cmd-template

Шаблон командной строки. Ниже показаны используемые по умолчанию значения. Для передачи опций применяются переменные окружения. «$CLANG_EXEC -DKERNEL $CLANG_OPTIONS $KERNEL_INC_OPTIONS \ -Wno-unused-value -Wno-pointer-sign -working-directory \ $WORKING_DIR -c $CLANG_SOURCE -target bpf -O2 -o -«

llvm.clang-opt

Опции, передаваемые clang.

llvm.kbuild-dir

Каталог kbuild. Если значение не задано, применяется /lib/modules/uname -r/build. При установке «» автоматическое определение заголовков ядра пропускается.

llvm.kbuild-opts

Опции, передаваемые make при обнаружении опций заголовков ядра.

llvm.dump-obj

Разрешает объектные файлы perf dump BPF, скомпилированные LLVM.

llvm.opts

Опции, передаваемые llc.

samples.*, samples.context

Определяет число наносекунд для отображения выборок в контексте браузера perf report.

scripts.*

Любая опция, добавляющая в меню интерактивного браузера perf script, вывод которого будет отображаться. Имя опции является именем сценария, значение задает командную строку сценария. Сценарий получает те же параметры, которые переданы perf, в частности -i perf.data, —cpu, —tid.

test

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

Для просмотра списка доступных тестов служит команда perf test list, которая позволяет ввести часть имени теста для поиска по подстроке.

Синтаксис

perf test [<options>] [{list <test-name-fragment>|[<test-name-fragments>|<test-numbers>]}]

Опции

-s, —skip

Пропустить тесты, указанные через запятую.

-v, —verbose

Подробный вывод.

-F, —dont-fork

Не создавать дочерних ветвлений для каждого теста, а выполнить все тесты в одном потоке.

version

Выводит версию двоичного файла perf. При указании опции —build-options выводится статус встроенных библиотек.

Синтаксис

perf version [--build-options]

Опции

—build-options

Показать статус встроенных библиотек.

Примеры использования perf

Для общего обзора — perf report —sort comm,dso.
Для выборки связанных событий — perf record -e ‘{cycles,instructions}:S’
Для сравнения результатов — perf diff [<old file> <new file>]
Логические опции могут обращаться с помощью no — perf report —no-children
Настройка вывода perf script — perf script -F event,ip,sym
Генерация сценария для ваших данных — perf script -g <lang>
Запись вывода perf stat — perf stat record <target workload>
Создание архива с символами для анализа на другой машине — perf archive
Поиск опций по ключевому слову — perf report -h <keyword>
использование родительского фильтра для просмотра пути конкретного вызова — perf report -p <regex>
Список событий, содержащих подстроку — perf list <keyword>
Просмотр списка сохраненных событий и атрибутов — perf evlist -v
Для нестандартного размещения файлов с символами используйте опцию —symfs <dir>
Для компактного вывода цепочки вызовов — perf report -g folded
Для просмотра отдельных выборок — perf script
Для просмотра только записей с издержками более 5% — perf report —percent-limit 5
Профилировка предсказаний ветвления — perf record -b, perf report
Просмотр ассемблерного контекста выборки record -b, perf script -F +brstackinsn —xed
Считать ветвления цепочками вызовов — perf report —branch-history
Подсчет событий каждую секунду (1000 мсек) — perf stat -I 1000
Вывод счетчиков событий в формате CSV — perf stat -x,
Видеть отладочную информацию — perf report -s sym,srcline
Профилирование адресов памяти — perf mem record, perf mem report
События точек трассировки — perf report -s trace_fields
Запись цепочек вызовов для каждой выборки — perf record -g
Запись каждого процесса определенного пользователя — perf record -u <user>
Пропуск идентификаторов сборки при записи — perf record -B
Смена частоты выборки на 100 Гц — perf record -F 100
Вывод ассемблерных инструкций с процентами — perf annotate <symbol>
Использовать стиль Intel для ассемблера — perf annotate -M intel
Иерархический вывод результатов — perf report —hierarchy
Упорядочение по издержкам для имен файлов и строк исходного кода — perf report -s srcline
Запись данных от всех процессоров — perf record -a
Просмотр текущих конфигурационных переменных perf config —list
Показ пользовательских переопределений конфигурации — perf config —user —list
Добавление Node.js USDT²⁷ — perf buildid-cache —add `which node`
Просмотр событий cacheline из сделанной записи — perf c2c report
Просмотр контекста выборок — perf report —sample 10 и выбор в меню context
Разделение выборок по времени — perf report —sort time,overhead,sym

Литература

[1] The Common Trace Format, https://diamon.org/ctf/#specification

[2] AMD64 Architecture Programmer’s Manual Volume 2: System Programming, 13.3 Instruction-Based Sampling, https://www.amd.com/system/files/TechDocs/24593.pdf

[3] Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 3B: System Programming Guide, https://www.intel.ru/content/www/ru/ru/architecture-and-technology/64-ia-32-architectures-software-developer-vol-3b-part-2-manual.html

[4] Static Probe Points, https://sourceware.org/gdb/onlinedocs/gdb/Static-Probe-Points.html

[5] The Linux Kernel documentation, https://www.kernel.org/doc/html/latest/.

По материалам документации ядра Linux

Николай Малых

nmalykh@protokols.ru

1Performance Monitoring Unit — блок мониторинга производительности.

2Inter-Process Communication — коммуникации между процессами.

3Non-Uniform Memory Access — неоднородный доступ к памяти.

4Эта опция в реальности не поддерживается для режима report.

5Эта опция в реальности не поддерживается для режима report.

6System Management Interrupt — прерывание для системных измерений

7Dynamic shared object — совместно используемый динамический объект.

8Text User Interface — текстовый пользовательский интерфейс.

9Debug with Arbitrary Record Format — отладка с произвольным форматом записи.

10Last Branch Record — запись последнего ветвления.

11Berkeley Packet Filter.

12Call Frame Information — информация кадра вызова.

13Transactional Synchronization Extension — расширение для синхронизации транзакций.

14Точность перехода по значению размера сильно зависит от конфигурации — числа и размера кольцевых буферов (-m). При больших размерах файлов (> 5 Мбайт) точность возрастает.

15Transactional Synchronization Extension — расширение синхронизации транзакций.

16Instruction Per Cycle — число инструкций на цикл.

17Instruction Pointer — указатель на инструкцию.

18Scalable Vector Graphics — масштабируемая векторная графика.

19Cache To Cache — из кэша в кэш.

20Last level Cache — кэш последнего уровня.

21Fill Buffer — заполнение буфера.

22В этом режиме perf не может корректно обрабатывать опции строки <command>, воспринимая их как свои опции. Использование двойных и одинарных кавычек не решает проблему.

23Statically Defined Tracepoint — заданные статически точки трассировки [4].

24Just-in-time — (компиляция) «на лету».

25Precise Event-Based Sampling — точная выборка на основе событий.

26Instruction Based Sampling — выборка на основе инструкций.

27User-Level Statically Defined Tracing — статически заданная трассировка на пользовательском уровне.

Рубрика: Linux, Измерения и тестирование, Мониторинг и управление | Комментарии отключены

Измерение производительности для трафика UDP

Опубликовано 16.10.2019 автором Nikolai Malykh

PDF

В прошлой публикации было рассмотрено измерение производительности сетевых операций для платы HiFive Unleashed с операционной системой Linux на базе ядра 5.2.9 с помощью программы iperf3 и заданного по умолчанию протокола TCP. Измерения показали, что скорость сетевого обмена в значительной мере определяется не возможностями платы и ядра Linux, а параметрами управления потоком данных в реализации протокола TCP. Поскольку для нас основной интерес представляют возможности процессоров Freedom U540, установленных на плате HiFive Unleashed и собранного специально для этой платы ядра Linux 5.2.9, было принято решение провести измерения скорости сетевого обмена по протоколу UDP.

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

В тесте применялась плата HiFive Unleashed с ОС Linux на базе специально собранного ядра версии 5.2.9 и хост x86_64 с двумя процессорами Xeon (суммарно 40 ядер). Сначала измерения проводились с клиентом HiFive и сервером x86_64, затем хосты менялись ролями

Клиент HiFive

Принятая по умолчанию скорость (1 Мбит/с)

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 52003 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   1.00-2.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   2.00-3.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   3.00-4.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   4.00-5.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   5.00-6.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   6.00-7.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   7.00-8.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   8.00-9.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   9.00-10.00  sec   127 KBytes  1.04 Mbits/sec  90   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  1.25 MBytes  1.05 Mbits/sec  0.000 ms  0/905 (0%)  sender 
[  5]   0.00-10.00  sec  1.25 MBytes  1.05 Mbits/sec  0.014 ms  0/905 (0%)  receiver 

iperf Done.

2 Мбит/с

Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 45936 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   1.00-2.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   2.00-3.00   sec   243 KBytes  1.99 Mbits/sec  172   
[  5]   3.00-4.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   4.00-5.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   5.00-6.00   sec   243 KBytes  1.99 Mbits/sec  172   
[  5]   6.00-7.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   7.00-8.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   8.00-9.00   sec   243 KBytes  1.99 Mbits/sec  172   
[  5]   9.00-10.00  sec   245 KBytes  2.00 Mbits/sec  173   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  2.38 MBytes  2.00 Mbits/sec  0.000 ms  0/1727 (0%)  sender 
[  5]   0.00-10.00  sec  2.38 MBytes  2.00 Mbits/sec  0.019 ms  0/1727 (0%)  receiver 

iperf Done.

4 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 4M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 42367 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   488 KBytes  3.99 Mbits/sec  345   
[  5]   1.00-2.00   sec   489 KBytes  4.01 Mbits/sec  346   
[  5]   2.00-3.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   3.00-4.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   4.00-5.00   sec   489 KBytes  4.01 Mbits/sec  346   
[  5]   5.00-6.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   6.00-7.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   7.00-8.00   sec   489 KBytes  4.01 Mbits/sec  346   
[  5]   8.00-9.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   9.00-10.00  sec   488 KBytes  4.00 Mbits/sec  345   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  4.77 MBytes  4.00 Mbits/sec  0.000 ms  0/3453 (0%)  sender 
[  5]   0.00-10.00  sec  4.77 MBytes  4.00 Mbits/sec  0.029 ms  0/3453 (0%)  receiver 

iperf Done.

8 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 8M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 41812 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   976 KBytes  7.98 Mbits/sec  690   
[  5]   1.00-2.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   2.00-3.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   3.00-4.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   4.00-5.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   5.00-6.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   6.00-7.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   7.00-8.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   8.00-9.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   9.00-10.00  sec   977 KBytes  8.00 Mbits/sec  691   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  9.54 MBytes  8.00 Mbits/sec  0.000 ms  0/6905 (0%)  sender 
[  5]   0.00-10.00  sec  9.54 MBytes  8.00 Mbits/sec  0.063 ms  0/6905 (0%)  receiver 

iperf Done.

16 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 16M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 52891 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  1.90 MBytes  15.9 Mbits/sec  1377   
[  5]   1.00-2.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   2.00-3.00   sec  1.91 MBytes  16.0 Mbits/sec  1382   
[  5]   3.00-4.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   4.00-5.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   5.00-6.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   6.00-7.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   7.00-8.00   sec  1.91 MBytes  16.0 Mbits/sec  1382   
[  5]   8.00-9.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   9.00-10.00  sec  1.91 MBytes  16.0 Mbits/sec  1381   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  19.1 MBytes  16.0 Mbits/sec  0.000 ms  0/13808 (0%)  sender 
[  5]   0.00-10.00  sec  19.1 MBytes  16.0 Mbits/sec  0.074 ms  0/13808 (0%)  receiver 

iperf Done.

32 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 32M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 34927 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  3.81 MBytes  31.9 Mbits/sec  2760   
[  5]   1.00-2.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   2.00-3.00   sec  3.82 MBytes  32.0 Mbits/sec  2763   
[  5]   3.00-4.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   4.00-5.00   sec  3.82 MBytes  32.0 Mbits/sec  2763   
[  5]   5.00-6.00   sec  3.82 MBytes  32.0 Mbits/sec  2763   
[  5]   6.00-7.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   7.00-8.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   8.00-9.00   sec  3.82 MBytes  32.0 Mbits/sec  2763   
[  5]   9.00-10.00  sec  3.81 MBytes  32.0 Mbits/sec  2761   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  38.1 MBytes  32.0 Mbits/sec  0.000 ms  0/27621 (0%)  sender 
[  5]   0.00-10.00  sec  38.1 MBytes  32.0 Mbits/sec  0.060 ms  0/27621 (0%)  receiver 

iperf Done.

64 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 64M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 39289 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  7.62 MBytes  63.9 Mbits/sec  5516   
[  5]   1.00-2.00   sec  7.62 MBytes  64.0 Mbits/sec  5521   
[  5]   2.00-3.00   sec  7.62 MBytes  63.9 Mbits/sec  5516   
[  5]   3.00-4.00   sec  7.65 MBytes  64.1 Mbits/sec  5538   
[  5]   4.00-5.00   sec  7.64 MBytes  64.1 Mbits/sec  5531   
[  5]   5.00-6.00   sec  7.63 MBytes  64.0 Mbits/sec  5522   
[  5]   6.00-7.00   sec  7.62 MBytes  64.0 Mbits/sec  5521   
[  5]   7.00-8.00   sec  7.64 MBytes  64.1 Mbits/sec  5532   
[  5]   8.00-9.00   sec  7.61 MBytes  63.8 Mbits/sec  5509   
[  5]   9.00-10.00  sec  7.65 MBytes  63.9 Mbits/sec  5539   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  76.3 MBytes  64.0 Mbits/sec  0.000 ms  0/55245 (0%)  sender 
[  5]   0.00-10.00  sec  76.3 MBytes  64.0 Mbits/sec  0.073 ms  0/55245 (0%)  receiver 

iperf Done.

128 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 128M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 49324 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  10.6 MBytes  88.6 Mbits/sec  7650   
[  5]   1.00-2.00   sec  10.6 MBytes  88.7 Mbits/sec  7658   
[  5]   2.00-3.00   sec  10.6 MBytes  89.1 Mbits/sec  7689   
[  5]   3.00-4.00   sec  10.6 MBytes  88.6 Mbits/sec  7645   
[  5]   4.00-5.00   sec  10.5 MBytes  88.3 Mbits/sec  7623   
[  5]   5.00-6.00   sec  10.5 MBytes  87.9 Mbits/sec  7590   
[  5]   6.00-7.00   sec  10.4 MBytes  87.6 Mbits/sec  7563   
[  5]   7.00-8.00   sec  10.4 MBytes  87.4 Mbits/sec  7549   
[  5]   8.00-9.00   sec  10.7 MBytes  90.0 Mbits/sec  7766   
[  5]   9.00-10.00  sec  10.7 MBytes  90.0 Mbits/sec  7771   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec   106 MBytes  88.6 Mbits/sec  0.000 ms  0/76504 (0%)  sender 
[  5]   0.00-10.00  sec   106 MBytes  88.6 Mbits/sec  0.077 ms  0/76504 (0%)  receiver 

iperf Done.

256 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 256M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 50317 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  10.6 MBytes  88.6 Mbits/sec  7650   
[  5]   1.00-2.00   sec  10.6 MBytes  88.7 Mbits/sec  7660   
[  5]   2.00-3.00   sec  10.6 MBytes  88.9 Mbits/sec  7676   
[  5]   3.00-4.00   sec  10.7 MBytes  89.4 Mbits/sec  7718   
[  5]   4.00-5.00   sec  10.6 MBytes  89.0 Mbits/sec  7687   
[  5]   5.00-6.00   sec  10.6 MBytes  88.9 Mbits/sec  7673   
[  5]   6.00-7.00   sec  10.6 MBytes  88.9 Mbits/sec  7678   
[  5]   7.00-8.00   sec  10.7 MBytes  89.8 Mbits/sec  7752   
[  5]   8.00-9.00   sec  10.7 MBytes  89.7 Mbits/sec  7741   
[  5]   9.00-10.00  sec  10.7 MBytes  89.5 Mbits/sec  7725   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec   106 MBytes  89.1 Mbits/sec  0.000 ms  0/76960 (0%)  sender 
[  5]   0.00-10.00  sec   106 MBytes  89.1 Mbits/sec  0.083 ms  0/76960 (0%)  receiver 

iperf Done.

512 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 512M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 44858 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  8.35 MBytes  70.0 Mbits/sec  6046   
[  5]   1.00-2.00   sec  8.50 MBytes  71.3 Mbits/sec  6152   
[  5]   2.00-3.00   sec  8.45 MBytes  70.9 Mbits/sec  6122   
[  5]   3.00-4.00   sec  7.75 MBytes  65.0 Mbits/sec  5615   
[  5]   4.00-5.00   sec  7.66 MBytes  64.3 Mbits/sec  5548   
[  5]   5.00-6.00   sec  7.64 MBytes  64.1 Mbits/sec  5530   
[  5]   6.00-7.00   sec  7.62 MBytes  63.9 Mbits/sec  5517   
[  5]   7.00-8.00   sec  7.77 MBytes  65.2 Mbits/sec  5627   
[  5]   8.00-9.00   sec  7.77 MBytes  65.1 Mbits/sec  5624   
[  5]   9.00-10.00  sec  7.72 MBytes  64.8 Mbits/sec  5594   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  79.2 MBytes  66.5 Mbits/sec  0.000 ms  0/57375 (0%)  sender 
[  5]   0.00-10.00  sec  79.2 MBytes  66.5 Mbits/sec  0.021 ms  0/57375 (0%)  receiver 

iperf Done.

1000 Мбит/с

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 1000M  
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 56734 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  7.69 MBytes  64.5 Mbits/sec  5571   
[  5]   1.00-2.00   sec  7.69 MBytes  64.5 Mbits/sec  5570   
[  5]   2.00-3.00   sec  7.69 MBytes  64.6 Mbits/sec  5572   
[  5]   3.00-4.00   sec  7.67 MBytes  64.3 Mbits/sec  5554   
[  5]   4.00-5.00   sec  7.67 MBytes  64.3 Mbits/sec  5555   
[  5]   5.00-6.00   sec  7.63 MBytes  64.0 Mbits/sec  5527   
[  5]   6.00-7.00   sec  7.62 MBytes  63.9 Mbits/sec  5520   
[  5]   7.00-8.00   sec  7.68 MBytes  64.5 Mbits/sec  5565   
[  5]   8.00-9.00   sec  7.65 MBytes  64.2 Mbits/sec  5540   
[  5]   9.00-10.00  sec  7.63 MBytes  64.0 Mbits/sec  5522   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  76.6 MBytes  64.3 Mbits/sec  0.000 ms  0/55496 (0%)  sender 
[  5]   0.00-10.00  sec  76.6 MBytes  64.3 Mbits/sec  0.033 ms  0/55496 (0%)  receiver 

iperf Done.

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

Из приведенных результатов и графика (Рисунок 1) видно, что в диапазоне скоростей передачи трафика клиентом HiFive между 64 и 128 Мбит/с наступает насыщение, а затем даже некоторое снижение определяемой iperf3 скорости и числа переданных дейтаграмм. Исследуем интервал скоростей 64-256 Мбит/с более подробно.

Рисунок 1. Зависимость измеренной скорости от значения опции iperf3 -b.

Поведение в интервале скоростей 64 — 128 Мбит/с

При скорости 70 Мбит/с скорость передачи, заданная в iperf3 еще совпадает с измеренной скоростью, как можно видеть из приведенного ниже вывода

root@freedom-u540:~# iperf3 -c 192.168.0.10 -u -b 70M 
Connecting to host 192.168.0.10, port 5201 
[  5] local 192.168.0.3 port 39737 connected to 192.168.0.10 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  8.33 MBytes  69.8 Mbits/sec  6030   
[  5]   1.00-2.00   sec  8.33 MBytes  69.9 Mbits/sec  6032   
[  5]   2.00-3.00   sec  8.34 MBytes  70.0 Mbits/sec  6043   
[  5]   3.00-4.00   sec  8.36 MBytes  70.2 Mbits/sec  6055   
[  5]   4.00-5.00   sec  8.35 MBytes  70.0 Mbits/sec  6049   
[  5]   5.00-6.00   sec  8.34 MBytes  70.0 Mbits/sec  6040   
[  5]   6.00-7.00   sec  8.32 MBytes  69.8 Mbits/sec  6027   
[  5]   7.00-8.00   sec  8.35 MBytes  70.0 Mbits/sec  6044   
[  5]   8.00-9.00   sec  8.37 MBytes  70.2 Mbits/sec  6059   
[  5]   9.00-10.00  sec  8.35 MBytes  70.1 Mbits/sec  6048   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  83.4 MBytes  70.0 Mbits/sec  0.000 ms  0/60427 (0%)  sender 
[  5]   0.00-10.00  sec  83.4 MBytes  70.0 Mbits/sec  0.072 ms  0/60427 (0%)  receiver 

iperf Done.

Заметное насыщение начинается в интервале скоростей 71 — 72 Мбит/с. Не будем загромождать текст подробным выводом измерений в диапазоне и покажем лишь график усредненных по нескольким измерениям значений скорости в зависимости параметра -b в команде iperf3. Отметим, что при скорости передачи выше 70 Мбит/с утилита top показывала близкую к 100% загрузку процессора, поэтому результаты iperf3 отличались от измерения к измерению и на графике (Рисунок 2) приведены усредненные значения.

Рисунок 2. Насыщение скорости передачи трафика UDP.

С момента насыщения, как можно видеть из приведенного выше вывода для скоростей выше 64 Мбит/с измеренная скорость в каждом интервале iperf3 колеблется в значительных пределах. Это обусловлено тем, что генерация пакетов iperf3 практически полностью загружает процессоры, поэтому реальная скорость генерации зависит от текущей загрузки процессоров фоновыми задачами с высоким приоритетом (системные процессы).

Сервер HiFive

Принятая по умолчанию скорость (1 Мбит/с)

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 42358 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   1.00-2.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   2.00-3.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   3.00-4.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   4.00-5.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   5.00-6.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   6.00-7.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   7.00-8.00   sec   129 KBytes  1.05 Mbits/sec  91   
[  5]   8.00-9.00   sec   127 KBytes  1.04 Mbits/sec  90   
[  5]   9.00-10.00  sec   129 KBytes  1.05 Mbits/sec  91   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  1.25 MBytes  1.05 Mbits/sec  0.000 ms  0/906 (0%)  sender 
[  5]   0.00-10.00  sec  1.25 MBytes  1.05 Mbits/sec  0.005 ms  0/906 (0%)  receiver 

iperf Done.

2 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 2M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 37942 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   1.00-2.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   2.00-3.00   sec   243 KBytes  1.99 Mbits/sec  172   
[  5]   3.00-4.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   4.00-5.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   5.00-6.00   sec   243 KBytes  1.99 Mbits/sec  172   
[  5]   6.00-7.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   7.00-8.00   sec   245 KBytes  2.00 Mbits/sec  173   
[  5]   8.00-9.00   sec   243 KBytes  1.99 Mbits/sec  172   
[  5]   9.00-10.00  sec   245 KBytes  2.00 Mbits/sec  173   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  2.38 MBytes  2.00 Mbits/sec  0.000 ms  0/1727 (0%)  sender 
[  5]   0.00-10.00  sec  2.38 MBytes  2.00 Mbits/sec  0.006 ms  0/1727 (0%)  receiver 

iperf Done.

4 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 4M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 54584 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   1.00-2.00   sec   489 KBytes  4.01 Mbits/sec  346   
[  5]   2.00-3.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   3.00-4.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   4.00-5.00   sec   489 KBytes  4.01 Mbits/sec  346   
[  5]   5.00-6.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   6.00-7.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   7.00-8.00   sec   489 KBytes  4.01 Mbits/sec  346   
[  5]   8.00-9.00   sec   488 KBytes  4.00 Mbits/sec  345   
[  5]   9.00-10.00  sec   488 KBytes  4.00 Mbits/sec  345   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  4.77 MBytes  4.00 Mbits/sec  0.000 ms  0/3453 (0%)  sender 
[  5]   0.00-10.00  sec  4.77 MBytes  4.00 Mbits/sec  0.023 ms  0/3453 (0%)  receiver 

iperf Done.

8 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 8M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 42485 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   1.00-2.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   2.00-3.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   3.00-4.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   4.00-5.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   5.00-6.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   6.00-7.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   7.00-8.00   sec   977 KBytes  8.00 Mbits/sec  691   
[  5]   8.00-9.00   sec   976 KBytes  7.99 Mbits/sec  690   
[  5]   9.00-10.00  sec   977 KBytes  8.00 Mbits/sec  691   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  9.54 MBytes  8.00 Mbits/sec  0.000 ms  0/6906 (0%)  sender 
[  5]   0.00-10.00  sec  9.54 MBytes  8.00 Mbits/sec  0.005 ms  0/6906 (0%)  receiver 

iperf Done.

16 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 16M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 51701 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  1.91 MBytes  16.0 Mbits/sec  1380   
[  5]   1.00-2.00   sec  1.91 MBytes  16.0 Mbits/sec  1382   
[  5]   2.00-3.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   3.00-4.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   4.00-5.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   5.00-6.00   sec  1.91 MBytes  16.0 Mbits/sec  1382   
[  5]   6.00-7.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   7.00-8.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   8.00-9.00   sec  1.91 MBytes  16.0 Mbits/sec  1381   
[  5]   9.00-10.00  sec  1.91 MBytes  16.0 Mbits/sec  1381   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  19.1 MBytes  16.0 Mbits/sec  0.000 ms  0/13811 (0%)  sender 
[  5]   0.00-10.00  sec  19.1 MBytes  16.0 Mbits/sec  0.027 ms  0/13811 (0%)  receiver 

iperf Done.

32 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 32M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 59259 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  3.81 MBytes  32.0 Mbits/sec  2761   
[  5]   1.00-2.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   2.00-3.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   3.00-4.00   sec  3.82 MBytes  32.0 Mbits/sec  2763   
[  5]   4.00-5.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   5.00-6.00   sec  3.82 MBytes  32.0 Mbits/sec  2763   
[  5]   6.00-7.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   7.00-8.00   sec  3.82 MBytes  32.0 Mbits/sec  2763   
[  5]   8.00-9.00   sec  3.81 MBytes  32.0 Mbits/sec  2762   
[  5]   9.00-10.00  sec  3.81 MBytes  32.0 Mbits/sec  2762   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  38.1 MBytes  32.0 Mbits/sec  0.000 ms  0/27622 (0%)  sender 
[  5]   0.00-10.00  sec  38.1 MBytes  32.0 Mbits/sec  0.058 ms  0/27622 (0%)  receiver 

iperf Done.

64 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 64M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 54983 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  7.62 MBytes  63.9 Mbits/sec  5521   
[  5]   1.00-2.00   sec  7.63 MBytes  64.0 Mbits/sec  5525   
[  5]   2.00-3.00   sec  7.63 MBytes  64.0 Mbits/sec  5524   
[  5]   3.00-4.00   sec  7.63 MBytes  64.0 Mbits/sec  5525   
[  5]   4.00-5.00   sec  7.63 MBytes  64.0 Mbits/sec  5525   
[  5]   5.00-6.00   sec  7.63 MBytes  64.0 Mbits/sec  5525   
[  5]   6.00-7.00   sec  7.63 MBytes  64.0 Mbits/sec  5525   
[  5]   7.00-8.00   sec  7.63 MBytes  64.0 Mbits/sec  5525   
[  5]   8.00-9.00   sec  7.63 MBytes  64.0 Mbits/sec  5524   
[  5]   9.00-10.00  sec  7.63 MBytes  64.0 Mbits/sec  5525   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  76.3 MBytes  64.0 Mbits/sec  0.000 ms  0/55244 (0%)  sender 
[  5]   0.00-10.00  sec  76.3 MBytes  64.0 Mbits/sec  0.066 ms  0/55244 (0%)  receiver 

iperf Done.

128 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 128M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 47960 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  15.2 MBytes   128 Mbits/sec  11041   
[  5]   1.00-2.00   sec  15.3 MBytes   128 Mbits/sec  11049   
[  5]   2.00-3.00   sec  15.3 MBytes   128 Mbits/sec  11050   
[  5]   3.00-4.00   sec  15.3 MBytes   128 Mbits/sec  11051   
[  5]   4.00-5.00   sec  15.3 MBytes   128 Mbits/sec  11049   
[  5]   5.00-6.00   sec  15.3 MBytes   128 Mbits/sec  11050   
[  5]   6.00-7.00   sec  15.3 MBytes   128 Mbits/sec  11049   
[  5]   7.00-8.00   sec  15.3 MBytes   128 Mbits/sec  11050   
[  5]   8.00-9.00   sec  15.3 MBytes   128 Mbits/sec  11049   
[  5]   9.00-10.00  sec  15.3 MBytes   128 Mbits/sec  11051   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec   153 MBytes   128 Mbits/sec  0.000 ms  0/110489 (0%)  sender 
[  5]   0.00-10.00  sec   153 MBytes   128 Mbits/sec  0.080 ms  0/110489 (0%)  receiver 

iperf Done.

256 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 256M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 48766 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  30.5 MBytes   256 Mbits/sec  22084   
[  5]   1.00-2.00   sec  30.5 MBytes   256 Mbits/sec  22100   
[  5]   2.00-3.00   sec  30.5 MBytes   256 Mbits/sec  22099   
[  5]   3.00-4.00   sec  30.5 MBytes   256 Mbits/sec  22099   
[  5]   4.00-5.00   sec  30.5 MBytes   256 Mbits/sec  22098   
[  5]   5.00-6.00   sec  30.5 MBytes   256 Mbits/sec  22100   
[  5]   6.00-7.00   sec  30.5 MBytes   256 Mbits/sec  22098   
[  5]   7.00-8.00   sec  30.5 MBytes   256 Mbits/sec  22100   
[  5]   8.00-9.00   sec  30.5 MBytes   256 Mbits/sec  22101   
[  5]   9.00-10.00  sec  30.5 MBytes   256 Mbits/sec  22101   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec   305 MBytes   256 Mbits/sec  0.000 ms  0/220980 (0%)  sender 
[  5]   0.00-10.00  sec   219 MBytes   183 Mbits/sec  0.127 ms  62608/220852 (28%)  receiver 

iperf Done.

Вывод сервера

----------------------------------------------------------- 
Server listening on 5201 
----------------------------------------------------------- 
Accepted connection from 192.168.0.10, port 60266 
[  5] local 192.168.0.3 port 5201 connected to 192.168.0.10 port 48766 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-1.00   sec  21.9 MBytes   183 Mbits/sec  0.104 ms  6152/21982 (28%)   
[  5]   1.00-2.00   sec  21.9 MBytes   184 Mbits/sec  0.094 ms  6237/22078 (28%)   
[  5]   2.00-3.00   sec  21.9 MBytes   183 Mbits/sec  0.101 ms  6293/22117 (28%)   
[  5]   3.00-4.00   sec  21.8 MBytes   183 Mbits/sec  0.083 ms  6273/22092 (28%)   
[  5]   4.00-5.00   sec  21.8 MBytes   183 Mbits/sec  0.090 ms  6298/22099 (28%)   
[  5]   5.00-6.00   sec  21.9 MBytes   184 Mbits/sec  0.099 ms  6269/22110 (28%)   
[  5]   6.00-7.00   sec  21.9 MBytes   183 Mbits/sec  0.114 ms  6274/22098 (28%)   
[  5]   7.00-8.00   sec  21.9 MBytes   183 Mbits/sec  0.093 ms  6259/22100 (28%)   
[  5]   8.00-9.00   sec  21.8 MBytes   183 Mbits/sec  0.114 ms  6288/22099 (28%)   
[  5]   9.00-10.00  sec  21.8 MBytes   183 Mbits/sec  0.109 ms  6265/22076 (28%)   
[  5]  10.00-10.00  sec  1.41 KBytes  17.8 Mbits/sec  0.127 ms  0/1 (0%)   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec   219 MBytes   183 Mbits/sec  0.127 ms  62608/220852 (28%)  receiver

512 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 512M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 40006 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec  61.0 MBytes   512 Mbits/sec  44179   
[  5]   1.00-2.00   sec  61.0 MBytes   512 Mbits/sec  44195   
[  5]   2.00-3.00   sec  61.0 MBytes   512 Mbits/sec  44192   
[  5]   3.00-4.00   sec  61.0 MBytes   512 Mbits/sec  44197   
[  5]   4.00-5.00   sec  61.0 MBytes   512 Mbits/sec  44198   
[  5]   5.00-6.00   sec  61.0 MBytes   512 Mbits/sec  44207   
[  5]   6.00-7.00   sec  61.0 MBytes   512 Mbits/sec  44205   
[  5]   7.00-8.00   sec  61.0 MBytes   512 Mbits/sec  44194   
[  5]   8.00-9.00   sec  61.0 MBytes   512 Mbits/sec  44198   
[  5]   9.00-10.00  sec  61.0 MBytes   512 Mbits/sec  44194   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec   610 MBytes   512 Mbits/sec  0.000 ms  0/441959 (0%)  sender 
[  5]   0.00-10.02  sec   209 MBytes   175 Mbits/sec  0.075 ms  290265/441703 (66%)  receiver 

iperf Done.

Вывод сервера

----------------------------------------------------------- 
Server listening on 5201 
----------------------------------------------------------- 
Accepted connection from 192.168.0.10, port 60312 
[  5] local 192.168.0.3 port 5201 connected to 192.168.0.10 port 40006 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-1.00   sec  20.9 MBytes   175 Mbits/sec  0.131 ms  28013/43126 (65%)   
[  5]   1.00-2.00   sec  20.9 MBytes   175 Mbits/sec  0.068 ms  29032/44139 (66%)   
[  5]   2.00-3.00   sec  20.9 MBytes   175 Mbits/sec  0.077 ms  29134/44249 (66%)   
[  5]   3.00-4.00   sec  20.9 MBytes   175 Mbits/sec  0.123 ms  29107/44240 (66%)   
[  5]   4.00-5.00   sec  20.9 MBytes   175 Mbits/sec  0.100 ms  29067/44191 (66%)   
[  5]   5.00-6.00   sec  20.9 MBytes   175 Mbits/sec  0.085 ms  29008/44141 (66%)   
[  5]   6.00-7.00   sec  20.9 MBytes   175 Mbits/sec  0.129 ms  29117/44232 (66%)   
[  5]   7.00-8.00   sec  20.9 MBytes   175 Mbits/sec  0.129 ms  29130/44240 (66%)   
[  5]   8.00-9.00   sec  20.9 MBytes   175 Mbits/sec  0.119 ms  29083/44196 (66%)   
[  5]   9.00-10.00  sec  20.9 MBytes   175 Mbits/sec  0.077 ms  29024/44133 (66%)   
[  5]  10.00-10.02  sec   376 KBytes   172 Mbits/sec  0.075 ms  550/816 (67%)   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.02  sec   209 MBytes   175 Mbits/sec  0.075 ms  290265/441703 (66%)  receiver

1000 Мбит/с

[root@Lhotze ~]# iperf3 -c 192.168.0.3 -u -b 1000M 
Connecting to host 192.168.0.3, port 5201 
[  5] local 192.168.0.10 port 50966 connected to 192.168.0.3 port 5201 
[ ID] Interval           Transfer     Bitrate         Total Datagrams 
[  5]   0.00-1.00   sec   114 MBytes   956 Mbits/sec  82540   
[  5]   1.00-2.00   sec   114 MBytes   956 Mbits/sec  82564   
[  5]   2.00-3.00   sec   114 MBytes   956 Mbits/sec  82560   
[  5]   3.00-4.00   sec   114 MBytes   956 Mbits/sec  82564   
[  5]   4.00-5.00   sec   114 MBytes   956 Mbits/sec  82564   
[  5]   5.00-6.00   sec   114 MBytes   956 Mbits/sec  82564   
[  5]   6.00-7.00   sec   114 MBytes   956 Mbits/sec  82560   
[  5]   7.00-8.00   sec   114 MBytes   956 Mbits/sec  82571   
[  5]   8.00-9.00   sec   114 MBytes   956 Mbits/sec  82567   
[  5]   9.00-10.00  sec   114 MBytes   956 Mbits/sec  82563   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec  1.11 GBytes   956 Mbits/sec  0.000 ms  0/825617 (0%)  sender 
[  5]   0.00-10.02  sec   209 MBytes   175 Mbits/sec  0.097 ms  673764/825232 (82%)  receiver 

iperf Done.

Вывод сервера

----------------------------------------------------------- 
Server listening on 5201 
----------------------------------------------------------- 
Accepted connection from 192.168.0.10, port 60354 
[  5] local 192.168.0.3 port 5201 connected to 192.168.0.10 port 50966 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-1.00   sec  20.9 MBytes   175 Mbits/sec  0.172 ms  65460/80582 (81%)   
[  5]   1.00-2.00   sec  20.9 MBytes   175 Mbits/sec  0.085 ms  67393/82502 (82%)   
[  5]   2.00-3.00   sec  20.9 MBytes   175 Mbits/sec  0.104 ms  67515/82633 (82%)   
[  5]   3.00-4.00   sec  20.9 MBytes   175 Mbits/sec  0.074 ms  67355/82470 (82%)   
[  5]   4.00-5.00   sec  20.9 MBytes   175 Mbits/sec  0.116 ms  67487/82594 (82%)   
[  5]   5.00-6.00   sec  20.9 MBytes   175 Mbits/sec  0.156 ms  67488/82601 (82%)   
[  5]   6.00-7.00   sec  20.9 MBytes   175 Mbits/sec  0.076 ms  67307/82432 (82%)   
[  5]   7.00-8.00   sec  20.9 MBytes   175 Mbits/sec  0.077 ms  67422/82545 (82%)   
[  5]   8.00-9.00   sec  20.9 MBytes   175 Mbits/sec  0.110 ms  67564/82680 (82%)   
[  5]   9.00-10.00  sec  20.9 MBytes   175 Mbits/sec  0.097 ms  67450/82569 (82%)   
[  5]  10.00-10.02  sec   426 KBytes   168 Mbits/sec  0.097 ms  1323/1624 (81%)   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.02  sec   209 MBytes   175 Mbits/sec  0.097 ms  673764/825232 (82%)  receiver

Клиент x86_64 (2 процессора Xeon с общим числом ядер — 40) способен генерировать большой объем трафика, поэтому в этом тесте насыщение скорости определяется возможностями приема пакетов сервером HiFive Unleashed и насыщение наступает в диапазоне скоростей 128-256 Мбит/с, как можно видеть из графика (Рисунок 3).

Рисунок 3. Зависимость измеренной скорости от скорости генерации пакетов клиентом x86_64 (опция iperf3 -b).

Как и для случая клиента HiFive рассмотрим область начала насыщения более подробно. На рисунке 4 представлена область насыщения измеренной скорости и кривая роста ошибок (отмеченных клиентом потерь пакетов в %).

Рисунок 4. Насыщение скорости и рост числа потерянных пакетов

Здесь также программа iperf3 на стороне сервера HiFive Unleashed занимала практически все ресурсы процессора, поэтому измерение скорости и уровень потери в разных интервалах одного теста iperf3 менялись в широких пределах, как можно видеть из представленного ниже вывода для генерации тестовых пакетов клиентом со скоростью 160 Мбит/с. Это обусловлено нагрузкой на процессоры, создаваемой системными процессами, которые имеют более высокий приоритет, нежели задача iperf3.

----------------------------------------------------------- 
Server listening on 5201 
----------------------------------------------------------- 
Accepted connection from 192.168.0.10, port 37206 
[  5] local 192.168.0.3 port 5201 connected to 192.168.0.10 port 56421 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-1.00   sec  17.8 MBytes   149 Mbits/sec  0.078 ms  912/13801 (6.6%)   
[  5]   1.00-2.00   sec  19.1 MBytes   160 Mbits/sec  0.099 ms  0/13809 (0%)   
[  5]   2.00-3.00   sec  18.0 MBytes   151 Mbits/sec  0.172 ms  654/13696 (4.8%)   
[  5]   3.00-4.00   sec  12.8 MBytes   107 Mbits/sec  0.165 ms  4361/13638 (32%)   
[  5]   4.00-5.00   sec  18.5 MBytes   155 Mbits/sec  0.106 ms  681/14106 (4.8%)   
[  5]   5.00-6.00   sec  17.9 MBytes   150 Mbits/sec  0.131 ms  757/13699 (5.5%)   
[  5]   6.00-7.00   sec  13.4 MBytes   112 Mbits/sec  0.191 ms  4124/13804 (30%)   
[  5]   7.00-8.00   sec  16.4 MBytes   137 Mbits/sec  0.072 ms  2071/13933 (15%)   
[  5]   8.00-9.00   sec  14.7 MBytes   124 Mbits/sec  0.195 ms  3043/13705 (22%)   
[  5]   9.00-10.00  sec  13.3 MBytes   112 Mbits/sec  0.148 ms  4134/13793 (30%)   
- - - - - - - - - - - - - - - - - - - - - - - - - 
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams 
[  5]   0.00-10.00  sec   162 MBytes   136 Mbits/sec  0.148 ms  20737/137984 (15%)  receiver

Заключение

Проведенные измерения показывают, что максимальная скорость генерации трафика UDP программой iperf3 на плате HiFive Unleashed составляет приблизительно 80 Мбит/с, а максимальная скорость приема той же же программой примерно вдвое выше. Это задает диапазон скоростей приема и передачи пакетов, для которых целесообразно снять профили загрузки процессоров с целью получения более подробной информации об использовании системных ресурсов и узких местах системы.

Николай Малых

nmalykh@protokols.ru

Рубрика: Linux, RISC-V, Измерения и тестирование | Комментарии отключены

Справочник по Yocto Project (часть 2)

Глава 5. Структура каталога исходных кодов

5.1. Компоненты верхнего уровня

5.1.1. bitbake/

5.1.2. build/

5.1.3. documentation/

5.1.4. meta/

5.1.5. meta-poky/

5.1.6. meta-yocto-bsp/

5.1.7. meta-selftest/

5.1.8. meta-skeleton/

5.1.9. scripts/

5.1.9.1 oe-init-build-env

5.1.10. LICENSE, README и README.hardware

5.2. Каталог сборки build/

5.2.1. build/buildhistory

5.2.2. build/conf/local.conf

5.2.3. build/conf/bblayers.conf

5.2.4. build/conf/sanity_info

5.2.5. build/downloads/

5.2.6. build/sstate-cache/

5.2.7. build/tmp/

5.2.8. build/tmp/buildstats/

5.2.9. build/tmp/cache/

5.2.10. build/tmp/deploy/

5.2.11. build/tmp/deploy/deb/

5.2.12. build/tmp/deploy/rpm/

5.2.13. build/tmp/deploy/ipk/

5.2.14. build/tmp/deploy/licenses/

5.2.15. build/tmp/deploy/images/

5.2.16. build/tmp/deploy/sdk/

5.2.17. build/tmp/sstate-control/

5.2.18. build/tmp/sysroots-components/

5.2.19. build/tmp/sysroots/

5.2.20. build/tmp/stamps/

5.2.21. build/tmp/log/

5.2.22. build/tmp/work/

5.2.23. build/tmp/work/tunearch/recipename/version/

5.2.24. build/tmp/work-shared/

5.3. Метаданные — meta/

5.3.1. meta/classes/

5.3.2. meta/conf/

5.3.3. meta/conf/machine/

5.3.4. meta/conf/distro/

5.3.5. meta/conf/machine-sdk/

5.3.6. meta/files/

5.3.7. meta/lib/

5.3.8. meta/recipes-bsp/

5.3.9. meta/recipes-connectivity/

5.3.10. meta/recipes-core/

5.3.11. meta/recipes-devtools/

5.3.12. meta/recipes-extended/

5.3.13. meta/recipes-gnome/

5.3.14. meta/recipes-graphics/

5.3.15. meta/recipes-kernel/

5.3.16. meta/recipes-lsb4/

5.3.17. meta/recipes-multimedia/

5.3.18. meta/recipes-rt/

5.3.19. meta/recipes-sato/

5.3.20. meta/recipes-support/

5.3.21. meta/site/

5.3.22. meta/recipes.txt

Глава 6. Классы

6.1. allarch.bbclass

6.2. archiver.bbclass

6.3. autotools*.bbclass

6.4. base.bbclass

6.5. bash-completion.bbclass

6.6. bin_package.bbclass

6.7. binconfig.bbclass

6.8. binconfig-disabled.bbclass

6.9. blacklist.bbclass

6.10. bluetooth.bbclass

6.11. buildhistory.bbclass

6.12. buildstats.bbclass

6.13. buildstats-summary.bbclass

6.14. ccache.bbclass

6.15. chrpath.bbclass

6.16. clutter.bbclass

6.17. cmake.bbclass

5.1.1. `bitbake/`

5.1.2. `build/`

5.1.3. `documentation/`

5.1.4. `meta/`

5.1.5. `meta-poky/`

5.1.6. `meta-yocto-bsp/`

5.1.7. `meta-selftest/`

5.1.8. `meta-skeleton/`

5.1.9. `scripts/`

5.1.9.1 `oe-init-build-env`

5.1.10. `LICENSE, READMEиREADME.hardware`

5.2. Каталог сборки `build/`

5.2.1. `build/buildhistory`

5.2.2. `build/conf/local.conf`

5.2.3. `build/conf/bblayers.conf`

5.2.4. `build/conf/sanity_info`

5.2.5. `build/downloads/`

5.2.6. `build/sstate-cache/`

5.2.7. `build/tmp/`

5.2.8. `build/tmp/buildstats/`

5.2.9. `build/tmp/cache/`

5.2.10. `build/tmp/deploy/`

5.2.11. `build/tmp/deploy/deb/`

5.2.12. `build/tmp/deploy/rpm/`

5.2.13. `build/tmp/deploy/ipk/`

5.2.14. `build/tmp/deploy/licenses/`

5.2.15. `build/tmp/deploy/images/`

5.2.16. `build/tmp/deploy/sdk/`

5.2.17. `build/tmp/sstate-control/`

5.2.18. `build/tmp/sysroots-components/`

5.2.19. `build/tmp/sysroots/`

5.2.20. `build/tmp/stamps/`

5.2.21. `build/tmp/log/`

5.2.22. `build/tmp/work/`

5.2.23. `build/tmp/work/tunearch/recipename/`version`/`

5.2.24. `build/tmp/work-shared/`

5.3. Метаданные — `meta/`

5.3.1. `meta/classes/`

5.3.2. `meta/conf/`

5.3.3. `meta/conf/machine/`

5.3.4. `meta/conf/distro/`

5.3.5. `meta/conf/machine-sdk/`

5.3.6. `meta/files/`

5.3.7. `meta/lib/`

5.3.8. `meta/recipes-bsp/`

5.3.12. `meta/recipes-extended/`

5.3.13. `meta/recipes-gnome/`

5.3.14. `meta/recipes-graphics/`

5.3.15. `meta/recipes-kernel/`

5.3.16. `meta/recipes-lsb4/`

5.3.17. `meta/recipes-multimedia/`

5.3.18. `meta/recipes-rt/`

5.3.19. `meta/recipes-sato/`

5.3.20. `meta/recipes-support/`

5.3.21. `meta/site/`

5.3.22. `meta/recipes.txt`

6.1. `allarch.bbclass`

6.2. `archiver.bbclass`

6.3. `autotools*.bbclass`

6.4. `base.bbclass`

6.5. `bash-completion.bbclass`

6.6. `bin_package.bbclass`

6.7. `binconfig.bbclass`

6.8. `binconfig-disabled.bbclass`

6.9. `blacklist.bbclass`

6.10. `bluetooth.bbclass`

6.11. `buildhistory.bbclass`

6.12. `buildstats.bbclass`

6.13. `buildstats-summary.bbclass`

6.14. `ccache.bbclass`

6.15. `chrpath.bbclass`

6.16. `clutter.bbclass`

6.17. `cmake.bbclass`

6.21. `copyleft_filter.bbclass`

6.22. `core-image.bbclass`

6.23. `cpan*.bbclass`

6.24. `cross.bbclass`

6.25. `cross-canadian.bbclass`

6.26. `crosssdk.bbclass`

6.27. `debian.bbclass`