Руководство пользователя BitBake

image_print

BitBake User Manual

PDF

Richard Purdie, Chris Larson, and Phil Blundell

BitBake Community <bitbake-devel@lists.openembedded.org>

Copyright © 2004-2018 Richard Purdie, Chris Larson, and Phil Blundell

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.

Оглавление

Исключено в версии HTML.

Глава 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 включает библиотеку сборщика для извлечения исходного кода из локальных хранилищ, систем управления SCS1 или web-сайтов.

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

  • BitBake поддерживает модель «клиент-сервер» и может использоваться из командной строки или как служба XML-RPC, предоставляя несколько разных пользовательских интерфейсов.

1.2. История и назначение

BitBake исходно был частью проекта OE и его прообразом послужила система управления пакетами Portage из Gentoo Linux. 7 декабря 2004 г. член команды OE Chris Larson разделил проект на две части:

  • BitBake в качестве машины исполнения задач;

  • OE в качестве набора метаданных, используемых BitBake

Today, BitBake is the primary basis of the OE project, which is being used to build and maintain Linux distributions such as the Angstrom Distribution, and which is also being used as the build tool for Linux projects such as the 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:

  • описания пакетов (автор, домашняя страница, лицензия и т. п.);

  • версии заданий;

  • имеющиеся зависимости (при вборке и работе);

  • местоположение исходного кода и способ его извлечения;

  • потребность в применении правок, их местоположение и спрособ применения;

  • детали настройки и компиляции исходного кода;

  • место установки программ на целевой машине.

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

1.3.2. Файлы конфигурации

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

1.3.3. Классы

Файлы классов .bbclass содержат информацию, которая может совместно использоваться множеством файлов метаданных. Дерево источников BitBake в настоящее время содержит один файл метаданных классов base.bbclass
в
каталоге
classes. Классы из base.bbclass включаются автоматически для всех заданий и классов и содержат определения стандартных базовых задач, таких как выборка, распаковка, настройка (по умолчанию пуст), компиляция (запускается при наличии Makefile), инсталляция (по умолчанию пуст) и подготовка пакетов (по умолчанию пуст). Эти задачи часто переопределяются или расширяются другими классами, созданными при разработке проектов.

1.3.4. Уровни

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

Для иллюстрации применения уровней рассмотрим конфигурацию для конкретной целевой машины. Этот тип настройки обычно выделяют в специальный уровень, называемый уровнем BSP2. Настройки для машины следует изолировать от заданий и метаданных, поддерживающих, например, новую среду 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

  1. Клонирование 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
  2. Установка из дистрибутива не рекомендуется, поскольку в большинстве случаев она отстает по версии.

  3. Конкретная версия 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.

  4. Использование 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 исключает эти зависимости из графа, что может сделать граф более читаемым