<?xml version="1.0"?>
<!--
  ex:ts=4:sw=4:sts=4:et
  -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book lang="ru">
    <bookinfo>
        <title>BitBake руководство пользователя</title>
        <authorgroup>
            <corpauthor>BitBake Team</corpauthor>
        </authorgroup>
        <copyright>
            <year>2004, 2005, 2006</year>
            <holder>Chris Larson</holder>
            <holder>Phil Blundell</holder>
        </copyright>
        <legalnotice>
            <para>Руководство выпущено под лицензий c указанием авторства (Creative Commons Attribution License). Ознакомиться с лицензией можно по ссылке <ulink url="http://creativecommons.org/licenses/by/2.5/">http://creativecommons.org/licenses/by/2.5/</ulink> или отправив письмо в Creative Commons по адресу: 559 Nathan Abbott Way, Stanford, California 94305, USA.</para>
        </legalnotice>
    </bookinfo>
    <chapter>
        <title>Введение</title>
        <section>
            <title>Аннотация</title>
			<para>BitBake это инструмент для работы с метаданными и выполнения задач. Во многом он схож с GNU make и 
			другими существующествующими инструментами сборки. При его разработке многие идеи были почерпнуты из системы 
			управления пакетами portage, используемой в дистрибутиве Gentoo Linux. BitBake - фундамент проекта  
			<ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>, используемого для сборки и сопровождения 
			множества встраиваемых дистрибутивов Linux, включая такие как OpenZaurus и Familiar.
            </para>
        </section>
        <section>
            <title>Предпосылки и требования</title>
            <para>
	    До BitBake ни одна из систем сборки не удволетворяла должным образом растущим потребностям
	    встраиваемых дистрибутивов Linux. А в системах сборки традиционных дистрибутивов Linux  отсутствует 
	    необходимый функционал для сборки и сопровождения. Кроме этого ни одна из распрастраненных 
	    специализированных систем сборки (<emphasis>buildroot</emphasis> system), не была достаточно масштабируемой
	    и удобной в сопровождении.
	    </para>

      <para>Некоторые из важных требований предъявленных к BitBake:
            <itemizedlist>
                <listitem><para>Поддержка кросс-сборки.</para></listitem>
                <listitem><para>Поддержка зависимостей между пакетами (во время сборки для целевой платформы, во время сборки на родной платформе,и во время выполнения).</para></listitem>
                <listitem><para>Поддержка выполнения различных задач в пакете, включая получение исходных кодов, их распаковка, наложение патчей, настройка, и прочее.</para></listitem>
                <listitem><para>Независимость от дистрибутива Linux (как для платформы сборки, так и для целевой платформы).</para></listitem>
                <listitem><para>Независимость от архитектуры платформы сборки</para></listitem>
                <listitem><para>Поддержка различных целевых платформ и платформ сборки (включая cygwin, BSD и другие).</para></listitem>
                <listitem><para>Отсутствие привязок к корневой файловой системе ОС.</para></listitem>
                <listitem><para>Выбор необходимых метаданных в зависимости от целевой платформы, операционной системы, дистрибутива и архитектуры.</para></listitem>
                <listitem><para>Простое добавление дополнительных метаданных и пакетов.</para></listitem>
                <listitem><para>Простое взаимодействие между проектами которые используют BitBake для своих сборок.</para></listitem>
		<listitem><para>Предоставление механизма разделения общих метаданных между пакетами.</para></listitem>
            </itemizedlist>
        </para>
        <para>BitBake удволетворяет не только этим требованиям, но и многим другим, так как высокая гибкость и широкие возможности 
	всегда были на первом месте. В результате BitBake хорошо расширяем, позволяет встраивать код на Python и выполнять множество 
	различных задач.</para>
        </section>
    </chapter>
    <chapter>
        <title>Метаданные</title>
        <section>
            <title>Описание</title>
            <itemizedlist>
                <para>Метаданные BitBake делятся на 3 класса:</para>
                <listitem>
                    <para>Файлы настройки</para>
                </listitem>
                <listitem>
                    <para>.bb файлы</para>
                </listitem>
                <listitem>
                    <para>Классы</para>
                </listitem>
            </itemizedlist>
            <para>Далее описывается синтаксис операций поддерживаемых в метаданных Bitbake с указанием области действия 
	    (если она ограничена) и приводятся примеры использования операций в метаданных BitBake.
            </para>
            <section>
                <title>Операция присвоения</title>
                <para><screen><varname>VARIABLE</varname> = "value"</screen></para>
                <para>В этом примере, после выполнения операции переменная <varname>VARIABLE</varname> будет иметь значение 
                <literal>value</literal>.</para>
            </section>
            <section>
                <title>Использование ссылок на переменные</title>
                <para>BitBake поддерживает использование в значениях ссылок на другие переменные, через синтаксис аналогичный в скриптах shell</para>
                <para><screen><varname>A</varname> = "aval"
<varname>B</varname> = "pre${A}post"</screen></para>
                <para> В результате выполнения операций переменная <varname>A</varname> будет иметь значение <literal>aval</literal>, 
                а <varname>B</varname> будет иметь значение <literal>preavalpost</literal>.</para>
            </section>
            <section>
                <title>Операция присвоения значения по умолчанию (?=)</title>
                <para><screen><varname>A</varname> ?= "aval"</screen></para>
                <para>Если переменная <varname>A</varname> до вызова этой операции уже имела значение, то ее значение не изменится. 
                Если же переменная <varname>A</varname> не имела значения до вызова этой операции, то переменная <varname>A</varname> 
                будет иметь значение <literal>aval</literal>.  Заметим что, если имеется множественое использование операции, сработает только 
                первая из них.
                </para>
            </section>
            <section>
                <title>Операция присвоения значения по умолчанию (??=)</title>
                <para><screen><varname>A</varname> ??= "somevalue"</screen></para>
                <para><screen><varname>A</varname> ??= "someothervalue"</screen></para>
                <para>Если переменная <varname>A</varname> до вызова этой операции уже имела значение, то ее значение не изменится.  
                Если переменная <varname>A</varname> не имела значения до  вызова этой операции, 
                то переменная <varname>A</varname> будет иметь значение <literal>someothervalue</literal>.
                Это "ленивая" версия операции ?=, в случае множественного использования операции, срабатывает 
                последняя из них.</para>
            </section>
            <section>
                <title>Присвоение с заменой (:=)</title>
                <para>:= в результате выполнения операции, значение переменной, заменяется. </para>
                <para><screen><varname>T</varname> = "123"
<varname>A</varname> := "${B} ${A} test ${T}"
<varname>T</varname> = "456"
<varname>B</varname> = "${T} bval"

<varname>C</varname> = "cval"
<varname>C</varname> := "${C}append"</screen></para>
                <para>В примере, в результате выполнения операций перменная<varname>A</varname> будет иметь значение <literal> test 123</literal>, 
                переменная <varname>B</varname> будет иметь значение <literal>456 bval</literal>, а переменная <varname>C</varname> 
                будет иметь значение <literal>cvalappend</literal>.</para>
            </section>
            <section>
                <title>Постфиксная операция добавления (+=) и префиксная операция добавления (=+)</title>
                <para><screen><varname>B</varname> = "bval"
<varname>B</varname> += "additionaldata"
<varname>C</varname> = "cval"
<varname>C</varname> =+ "test"</screen></para>
                <para>В результате выполнения, <varname>B</varname> будет иметь значение <literal>bval additionaldata</literal>, 
                а <varname>C</varname> будет иметь значение <literal>test cval</literal>.</para>

            </section>
            <section>
                <title>Постфиксная операция добавления (.=) и префиксная операция добавления (=.) без включения пробелов</title>
                    <para><screen><varname>B</varname> = "bval"
<varname>B</varname> .= "additionaldata"
<varname>C</varname> = "cval"
<varname>C</varname> =. "test"</screen></para>
                <para>В результате выполнения, <varname>B</varname> будет иметь значение <literal>bvaladditionaldata</literal>, 
                а <varname>C</varname> будет иметь значение <literal>testcval</literal>.
                 В отличии от постфиксной (+=) и префиксной (=+) операций добавления, эти операции не добавляют пробел.</para>
            </section>
            <section>
                <title>Операция условного присвоения</title>
                <para>OVERRIDES это список разделенный <quote>:</quote>, где каждый элемент указывает на условия которые будут проверяться.  
                К примеру если у вас есть переменная обусловлена <quote>arm</quote>, и <quote>arm</quote> присутствует в OVERRIDES, 
                то более обусловленная версия переменной <quote>arm</quote> будет использована вместо менее необусловленной.  
		К примеру:</para>
                <para>
                <screen>
<varname>OVERRIDES</varname> = "architecture:os:machine"
<varname>TEST</varname> = "defaultvalue"
<varname>TEST_os</varname> = "osspecificvalue"
<varname>TEST_condnotinoverrides</varname> = "othercondvalue"
				</screen>
				</para>
                <para>В результате переменная <varname>TEST</varname> будет содержать <literal>osspecificvalue</literal>, 
                так как условие <quote>os</quote> присутствует в списке <varname>OVERRIDES</varname>.</para>
            </section>
            <section>
                <title>Условное добавление</title>
                <para>BitBake так же поддерживает условные постфиксные и префиксные операции над переменными 
                с использованием списка OVERRIDES.  К примеру:</para>
                <para>
                	<screen>
<varname>DEPENDS</varname> = "glibc ncurses"
<varname>OVERRIDES</varname> = "machine:local"
<varname>DEPENDS_append_machine</varname> = " libmad"
					</screen>
				</para>
                <para>В результате выполнения переменная <varname>DEPENDS</varname> будет иметь значение <literal>glibc ncurses libmad</literal>.
                </para>
            </section>
            <section>
                <title>Включение</title>
                <para>Деректива <literal>include</literal>, указывает BitBake обработать указанный вами файл и вставить его в необходимом месте,
                она похожа на такую же дерективу в <command>make</command>. Но однако, если в директиве <literal>include</literal> указан относительный путь,
				BitBake будет искать первое вхождение в <envar>BBPATH</envar>.</para>
            </section>
            <section>
                <title>Необходимое включение</title>
                <para>В отличии от директивы <literal>include</literal>, <literal>require</literal> вызывает ошибку ParseError 
                если файл для включения не найден. Во всем остальном она точно такая же как деректива <literal>include</literal>.</para>
            </section>
            <section>
                <title>Присвоение переменных при помощи Python</title>
                <para><screen><varname>DATE</varname> = "${@time.strftime('%Y%m%d',time.gmtime())}"</screen></para>
                <para>В результате <varname>DATE</varname> будет содержать текущую дату.</para>
            </section>
            <section>
                <title>Определение исполняемых задач в метаданных</title>
                <para><emphasis>Примечание:</emphasis> Эта возможность поддерживается только в .bb и .bbclass файлах.</para>
                <para><screen>do_mytask () {
    echo "Hello, world!"
}</screen></para>
                <para>Определение аналогично установке переменной, только в результате вызова задачи будет исполнен 
                shell сценарий.
                </para>
                <para><screen>python do_printdate () {
    import time
    print time.strftime('%Y%m%d', time.gmtime())
}</screen></para>
                <para>Аналогично выше приведенному определению задачи, но добавление флага python указывает BitBake,
                для запуска надо воспользоваться интерпретатором python.</para>
            </section>
            <section>
                <title>Определение функций на python в глобальной области Python</title>
                <para><emphasis>Примечание:</emphasis> Эта возможность поддерижвается только для .bb и .bbclass файлов.</para>
                <para><screen>def get_depends(bb, d):
    if bb.data.getVar('SOMECONDITION', d, True):
        return "dependencywithcond"
    else:
        return "dependency"

<varname>SOMECONDITION</varname> = "1"
<varname>DEPENDS</varname> = "${@get_depends(bb, d)}"</screen></para>
                <para>В результате <varname>DEPENDS</varname> будет содержать <literal>dependencywithcond</literal>.</para>
            </section>
            <section>
                <title>Флаги переменных</title>
                <para>Переменные могут быть ассоциированы с флагами для сохранения дополнительной информации о переменной.
                Некоторые флаги используются самим bitbake, но они их можно использовать и помимо этого, если вам это необходимо.
                Операции описанные выше работают с флагами как с обычными переменными. К примеру:
                </para>
                <para><screen><varname>VARIABLE</varname>[<varname>SOMEFLAG</varname>] = "value"</screen></para>
                <para>В результате,  к пермеенной <varname>VARIABLE</varname> добавляется флаг <varname>SOMEFLAG</varname> 
                со значением <literal>value</literal>.</para>
            </section>
            <section>
                <title>Наследование</title>
                <para><emphasis>Примечание:</emphasis> Эта возможность поддерживается только в .bb и .bbclass файлах.</para>
                <para>Деректива <literal>inherit</literal> указывает функционал каких классов будет использоваться в .bb файле.  
                Это позволяет организовать простейшую форму наследования. К примеру вы легко можете отделить задачи 
                использующие при сборке пакета autoconf и automake в отдельный bbclass, при подключении которого
                пакеты смогут использовать их. Указанный bbclass ищется по маске classes/filename.bbclass, 
                в списке путей <envar>BBPATH</envar>, где filename это имя класса который наследуется.</para>
            </section>
            <section>
                <title>Задачи</title>
                <para><emphasis>Примечание:</emphasis> Эта возможность поддерживается только в .bb и .bbclass файлах.</para>
                <para>В BitBake, каждый шаг который может быть запущен в файле .bb является задачей. 
                Команда <literal>addtask</literal> добавляет новые задачи (должны быть определены как python 
                исполняемые метаданные и должны начинаться с <quote>do_</quote>)  доступные для исполенния 
                и описывает зависимости между задачами.</para>
                <para><screen>python do_printdate () {
    import time
    print time.strftime('%Y%m%d', time.gmtime())
}

addtask printdate before do_build</screen></para>
                <para>В этом примере определяется задача на python и определяется зависимость от задачи do_build (задача по умолчанию). 
                Если кто-нибудь вызовет задачу do_build, то в результате сначала выполнится задача do_printdate, а затем do_build.</para>
            </section>
            <section>
                <title>События</title>
                <para><emphasis>Примечание:</emphasis> Эта возможность доступна только в .bb и .bbclass файлах.</para>
                <para>BitBake позволяет устанавливать обработчки событий.   События могут возникать во время различных операций, 
                таких как начало обработки .bb файла, старта указаной задачи, неудачного завершения задачи, удачного завершения задачи 
                и во многих других случаях. Это позволяет легко реализовывать такие вещи как email уведомения при ошибках сборки.
                 </para>
                <para><screen>addhandler myclass_eventhandler
python myclass_eventhandler() {
    from bb.event import NotHandled, getName
    from bb import data

    print "The name of the Event is %s" % getName(e)
    print "The file we run for is %s" % data.getVar('FILE', e.data, True)

    return NotHandled
}
</screen></para><para>
Этот обработчик событий вызывается каждый раз как просходит событие. Для обращения к событию определена глобальная переменная <varname>e</varname>.
<varname>e</varname>.data содержит копию bb.data. При помощи функции getName(<varname>e</varname>)
можно узнать имя возникшего события.</para><para> Таким образом выше приведенный обработчик выводит
имя события и значение переменной  <varname>FILE</varname>.</para>
            </section>
            <section>
                <title>Вариативности</title>
                <para>Для поддержки возможности создания множества вариантов сборки пакета используя один файл рецепт, в 
                Bitbake имеются два специальных расширения.</para>
                <para>Первое это <varname>BBCLASSEXTEND</varname>.
                Эта переменная содержит список разделенных пробелами классов, для наследования  в каждом из вариантов сборки рецепта.
                К пример, если присвоить: <screen>BBCLASSEXTEND = "native"</screen> то в результате станет доступен еще один вариант сборки.
                Этот вариант сборки будет дополнительно наследовать класс "native".</para>
                <para>Второе расширение это <varname>BBVERSIONS</varname>.
                Это расширение позволяет при помощи одного рецепта собирать множество версий пакета при помощи одного файла-рецепта,
                а так же позволяет указывать использовать условные операции (через <varname>OVERRIDES</varname>) для одной из версий или же 
                для заданого дапазона версий:
                </para>
                <para><screen>BBVERSIONS = "1.0 2.0 git"
SRC_URI_git = "git://someurl/somepath.git"</screen></para>
                <para><screen>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"</screen></para>
                <para>
                Так же стоит отметить, что имя диапазона по умолчанию совпадает с оригинальным именем рецепта,
                полученным от OE. К примеру файл рецепт foo_1.0.0+.bb будет иметь имя диапазона версий будет 1.0.0+
                Это позволяет использовать имя диапазона не только через условные операции, но и делает доступным использование его
                в путях поиска file:// (<varname>FILESPATH</varname>) через переменную <varname>BPV</varname> .
				</para>
            </section>
        </section>
        <section>
            <title>Поддержка зависимостей</title>
            <para>
            Начиная с версии 1.7.x Bitbake работает с метаданными на уровне задач, что позволяет использовать множество 
            потоков для их выполнения. Из-за этого требуется надежный метод разрешения зависимостей задачи перед ее выполнением. 
            </para>
            <section>
                <title>Зависимости внутри  .bb файла</title>
                <para>
                Когда зависимости задаются внутри .bb файла, то обработка осуществляется описаной выше дерективой addtask.
                </para>
            </section>

            <section>
                <title>DEPENDS</title>
                <para>DEPENDS описывает зависимости необходимые на стадии сборки.
               Флаг 'deptask' у задач может быть использован для указания, какая задача у каждой зависимости из DEPENDS 
               должна быть завершена до того как задача может быть запущена. 
               </para>
                <para><screen>do_configure[deptask] = "do_populate_staging"</screen></para>
                <para>это указывает, что задача do_populate_staging у каждой зависимости в списке DEPENDS должна быть завершена 
                до того как задача do_configure будет запущена.
                </para>
            </section>
            <section>
                <title>RDEPENDS</title>
                <para>RDEPENDS описывает зависимсти необходимые на стадии выполнения.
                Флаг 'reptask' у задач может быть использован для указания, какая задача у каждой зависимости из  RDEPENDS должна быть 
                завершена до того как задача может быть запущена. 
                </para>
                <para><screen>do_package_write[rdeptask] = "do_package"</screen></para>
                <para>это указывает, что задача do_package у каждой зависимости в  RDEPENDS должна быть завершена, 
                до того как задача do_package будет запущена.
                </para>
            </section>
            <section>
                <title>Рекурсивный DEPENDS</title>
                <para>
                Флаг 'recdeptask' у задач может быть использован для указания, какая задача у каждой зависимости 
                из DEPENDS должна быть завершена до того как задача может быть запущена.
                Этот флаг добавляет рекурсию, так что задачи зависимости из DEPENDS каждой зависимости из DEPENDS должен 
                так же удволетворять условию.  
                </para>
            </section>
            <section>
                <title>Рекурсивный RDEPENDS</title>
                <para>
                Флаг 'recrdeptask' у задач может быть использован для указания, какая задача у каждой зависимости 
                из RDEPENDS должна быть завершена до того как задача может быть запущена.
                Этот флаг добавляет рекурсию, так что задачи зависимости из RDEPENDS каждой зависимости из RDEPENDS должен 
                так же удволетворять условию.
                </para>
            </section>
            <section>
                <title>Зависимости между задачами</title>
                <para>Флаг 'depends' для задач является более простой формой задать зависимости 
                между задачами, чем использование  DEPENDS или RDEPENDS.
                </para>
                <para><screen>do_patch[depends] = "quilt-native:do_populate_staging"</screen></para>
                <para>это указываеть что задача do_populate_staging пакета quilt-native должна завершиться до того как
                будет запущена задача do_patch.</para>
            </section>
        </section>

        <section>
            <title>Разбор метаданых</title>
            <section>
                <title>Файлы настройки</title>
                <para>Первым классом метаданных в BitBake являются метаданные настройки.
                Эти метаданные глобальны и влияют на  <emphasis>все</emphasis> пакеты и запускаемые  задачи.
                 </para>
                <para>При старте Bitbake сначала ищет в текущем рабочем каталоге опциональный файл настройки "conf/bblayers.conf"  
               В этом файле ищется переменная BBLAYERS содержащая список 'слоев'-каталогов разделенных пробелами.
               В каждом каталоге из этого списка ищется и разбирается файл "conf/layer.conf" с установкой значения пременной 
               LAYERDIR в каталог где найден файл. Эти файлы создаются для автоматической установки перменной BBPATH и 
               корректной устрановки других переменных используя текущий рабочий каталог, как каталог сборки.
               </para>
                <para>Bitbake ожидает, что файл 'conf/bitbake.conf' находится в одном из каталогов списка  <envar>BBPATH</envar>.
                По умолчанию этот файл включает в себя дерективы подключения остальных метаданных (обычно это файлы 
                специфичные для архитектуры, платформы, <emphasis>локальных</emphasis> настроек и тому подобные)
                </para>
                <para>В файлах .conf разрешено только определение перменных и дерективы include.</para>
            </section>
            <section>
                <title>Классы</title>
                <para>Как было отмечено раньше классы BitBake реализуют простейший механизм наследования. 
                В введении в метаданные, указано что их обработка
                начинается при встрече дерективы <literal>inherit</literal>, 
                и моут быть размещены в classes подкаталоге каталогов из списка
                <envar>BBPATH</envar>.</para>
            </section>
            <section>
                <title>.bb Files</title>
                <para> BitBake (.bb) файл это логическая еденица используемая для запуска задач.
                Обычно они используются для сборки пакетов и могут зависеть друг от друга.
                Эти файлы ищутся при помощи перменной <varname>BBFILES</varname>, которая представляет 
                из себя список .bb файлов, разделенных пробелами. В списке поддерживаются маски, к примеру
                <literal>recipes/*/*.bb</literal>. 
                </para>
            </section>
        </section>
    </chapter>

    <chapter>
        <title>Поддерживаемые механизмы загрузки файлов</title>
        <section>
            <title>Аннотация</title>
            <para>BitBake предоставляет загрузку файлов через процедуру называемую 
            получение. SRC_URI обычно указывает BitBake какие файлы должны быть запрошены.
            Следущие разделы описывают какие существуют механизмы загрузки и какими параметрами они 
            обладают. Каждый механизм загрузки обладает своим набором переменных и параметров в 
            URI пары ключ и значение которых разделяются при  <quote>;</quote>.  Вид переменных и параметров 
            определяются механизмом загрузки, хотя BitBake пытается сохранять их постоянным среди механизмов 
            загрузки. 
            </para>
        </section>

        <section>
            <title>Механизм загрузки локальных файлов</title>
            <para>URN механизма загрузки локальных файлов <emphasis>file</emphasis>. 
            Путь может быть абсолютным или относительным. Если путь относительно, то используются переменные 
            <varname>FILESPATH</varname> и <varname>FILESDIR</varname> для поиска подходящего файла. Дополнительно на 
            поиск  может влиять переменная <varname>OVERRIDES</varname>. Путь может указывать как на отдельные файлы, 
            так и на каталоги.
<screen><varname>SRC_URI</varname>= "file://relativefile.patch"
<varname>SRC_URI</varname>= "file://relativefile.patch;this=ignored"
<varname>SRC_URI</varname>= "file:///Users/ich/very_important_software"
</screen>
            </para>
        </section>

        <section>
            <title>Механизм загрузки файлов из системы контроля версий CVS</title>
            <para>URN механизма загрузки из CVS<emphasis>cvs</emphasis>. 
            Этот механизм загрузки использует перменные <varname>DL_DIR</varname>, 
            <varname>SRCDATE</varname>, <varname>FETCHCOMMAND_cvs</varname>, 
            <varname>UPDATECOMMAND_cvs</varname>.
            <varname>DL_DIRS</varname> указывает где размещается временный каталог для полученния 
            данных, <varname>SRCDATE</varname> 
            указывает дату которая используется при получении данных (специальное значение "now" указывает на обновление 
            при каждой сборке), 
            <varname>FETCHCOMMAND</varname> и <varname>UPDATECOMMAND</varname> 
            указывают на команды, которые должны быть использованы для получения данных из CVS или их обновления.
            </para>
            <para>Поддерживаемые параметры это <varname>module</varname>, <varname>tag</varname>, <varname>date</varname>, 
            <varname>method</varname>, <varname>localdir</varname>, <varname>rsh</varname>. 
            Параметр <varname>module</varname> указывает какой модуль необходимо получить,
            <varname>tag</varname> описывает какой CVS TAG должен использваться при получении, по умолчанию он пуст.
            Пераметр <varname>date</varname> может быть указана для перекрытия переменной SRCDATE в настройках.  
            Специальное значение "now" будет вызывать обновление при каждой сборке.
            Параметр <varname>method</varname> по умолчанию установлен  в <emphasis>pserver</emphasis>, 
            Если <emphasis>ext</emphasis> используется, то <varname>rsh</varname> параметр вычисляется 
            и выставляется в качестве значения переменной <varname>CVS_RSH</varname>. 
            Параметр <varname>localdir</varname> используется для получения даных в каталог относительно переменной
           <varname>CVSDIR></varname>.
<screen><varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
<varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
</screen>
            </para>
        </section>

        <section>
            <title>HTTP/FTP механизм загрузки файлов</title>
            <para>URN для HTTP/FTP  <emphasis>http</emphasis>, <emphasis>https</emphasis> и <emphasis>ftp</emphasis>. 
            Этот механизм загрузки использует перменные 
            <varname>DL_DIR</varname>, <varname>FETCHCOMMAND_wget</varname>, <varname>PREMIRRORS</varname>, 
            <varname>MIRRORS</varname>. 
            
            Переменная <varname>DL_DIR</varname> определяет куда будут сохраняться полученные файлы,
            переменная <varname>FETCHCOMMAND</varname> указывает какой командой 
            будет осуществляться получение. <quote>${URI}</quote> и <quote>${FILES}</quote> 
            будут замененяются на uri и имя файла которого надо получить.
            Переменная <varname>PREMIRRORS</varname> указывает откуда сначала стоит попробовать получить файл. В 
            случае если произошла неудача, то проверяются все источники из <varname>MIRRORS</varname>.
            </para>
            <para>Поддерживается только один параметр, это <varname>md5sum</varname>. 
            После получения осуществляется вычисление <varname>md5sum</varname> файла и суммы сравниваются.
            </para>
            <para><screen><varname>SRC_URI</varname> = "http://oe.handhelds.org/not_there.aac;md5sum=12343"
<varname>SRC_URI</varname> = "ftp://oe.handhelds.org/not_there_as_well.aac;md5sum=1234"
<varname>SRC_URI</varname> = "ftp://you@oe.handheld.sorg/home/you/secret.plan;md5sum=1234"
</screen></para>
        </section>

        <section>
            <title>SVK механизм загрузки</title>
            <para>
            <emphasis>на данный момент НЕ поддерживается</emphasis>
            </para>
        </section>

        <section>
            <title>Механизм загрузки из системы контроля версий SVN</title>
            <para>URN механизма загрузки из SVN <emphasis>svn</emphasis>.
            </para>
            <para>Механизм загрузки использует переменные <varname>FETCHCOMMAND_svn</varname>, 
            <varname>DL_DIR</varname>, <varname>SRCDATE</varname>. 
            <varname>FETCHCOMMAND</varname> содержит команду для работы с subversion, 
            <varname>DL_DIR</varname> указывает каталог для сохранения, 
            <varname>SRCDATE</varname> указывает дату используемую для получения данных 
            (специальное значение "now" используется для обновления при каждой сборке).
            </para>
            <para>Поддерживаются следующие параметры: <varname>proto</varname>, <varname>rev</varname>. 
            <varname>proto</varname> указывает на используемый для обращения к хранилищу протокол, 
            <varname>rev</varname> указывает на используемую ревизию.
            </para>
            <para><screen><varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
<varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
</screen></para>
        </section>

        <section>
            <title>Механизм загрузки из система контроля версий GIT</title>
            <para>URN для механизма загрузки из GIT<emphasis>git</emphasis>.
            </para>
            <para>Используемые переменные <varname>DL_DIR</varname>, <varname>GITDIR</varname>. 
            <varname>DL_DIR</varname> используется для указания каталога сохранения полученных данных. 
            <varname>GITDIR</varname> используется в качестве базового каталога для клонирования git дерева.
            </para>
            <para>Поддерживаются следующие параметры <emphasis>tag</emphasis>, <emphasis>protocol</emphasis>. 
            <emphasis>tag</emphasis> указывает на используемый тег git, по умолчанию это <quote>master</quote>. 
            <emphasis>protocol</emphasis> указывает на используемый git протокол. По умолчанию это <quote>rsync</quote>.
            </para>
            <para><screen><varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
<varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
            </screen></para>
        </section>

    </chapter>


    <chapter>
        <title>Команда bitbake</title>
            <section>
                <title>Введение</title>
                <para>bitbake это основная команда в системе.  Она позволяет исполнять как задачи в отдельном .bb файле, 
                 так и исполнение заданной задачи из множества .bb файлов с учетом зависимостей между ними.
                 </para>
            </section>
            <section>
                <title>Использование и синтаксис вызовов</title>
                <para>
                    <screen><prompt>$ </prompt>bitbake --help
использование: bitbake [параметры] [пакет ...]

Исполняет указанную задача (по умолчанию 'build') для множества BitBake файлов.
Ожидается что переменная BBFILES определена и содержит список разделенных проблами
файлов, которые могут быть исполнены. BBFILES поддерживает маски. По умолчанию
BBFILES это список .bb файлов в текущем каталоге.

параметры:
  --version             показывает весрию программы и завершается.
  -h, --help            показывает это сообщение и завершается.
  -b BUILDFILE, --buildfile=BUILDFILE
                        выполняет задачи указаном .bb файле, игнорируя пакет 
                        в BBFILES.
  -k, --continue        продолжить  после ошибки, если возможно. 
  						В случае если выполнение цели провалено, то все зависящие от нее
  						не могут быть выполнены, остальные зависисти 
  						этих целей продолжат выполнятся.
  -f, --force           принудительно перезапустить указаную задачу, игнорируя ее статус
  -i, --interactive     перейти в интерактивный режим (BitBake shell).
  -c CMD, --cmd=CMD     Указать задачу для запуска. Учтите что таким образом выполняется 
  						только указанная задача, зависимости игнорируются.
  						К примеру если задача зависит от 'compile', то ее вызов не произойдет 
  						(используйте только когда вы знаете что делаете). В base.bbclass определена задача
  						listtasks вызов которые отобразит доступные для выполнения
  						задачи. 
  -r FILE, --read=FILE  считать этот файл до файла bitbake.conf
  -v, --verbose         увеличение подробности вывода производимых действий
  -D, --debug           Увеличить отладочный уровень. Может быть указан больше одного раза.
  -n, --dry-run         не исполнять, только отобразить действия.
  -p, --parse-only      выйти после завершения разбора файлов BB (только для разработчиков)
  -d, --disable-psyco   отключить использование JIT компилятора psyco (не рекомендуется)
  -s, --show-versions   показать текущую и предпочитаемую версию всех пакетов
  -e, --environment     показать глобальное окружение или специфичное для пакета окружение (это используется при bbread)
  -g, --graphviz        построить дерево зависимостей для указанных пакетов в dot синтаксисе graphiz
  -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
                        Игнорировать зависимости из списка при построении 
                        дерева зависимостей. Это позволит сделать дерево
                        более простым.
  -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
                        Показать отладочную информацию для указанных доменов отладки
  -P, --profile         профилирование исполняемой команды и вывод отчета


</screen>
                </para>
                <para>
                <example>
                    <title>Выполнение задачи в одном .bb файле</title>
                    <para>Для выполнения задач в одном файле, необходимо указать его в запросе после чего bitbake разбирает его и 
                    выполняет указаную задачу  (или <quote>build</quote> по умолчанию). При этом если необходимо, учитываются зависимости
                    между задачами.</para>
                    <para>Запуск задачи <quote>clean</quote>:</para>
                    <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb -c clean</screen></para>
                    <para>Запуск задачи <quote>build</quote>:</para>
                    <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb</screen></para>
                </example>
                </para>
                <para>
                <example>
                    <title>Выполнение задач в множестве .bb файлов</title>
                    <para>
                    При использовании множества файлов .bb возникают некоторые сложности. Во-первых  необходим механизм, который 
                    позволит сообщить bitbake, о том что файлы доступны и какой из них наобходим для выполнения. Во-вторых - 
                    механизм учета зависимостей для каждого.bb файла, как во время сборки, так и во время выполнения. В-третьих - 
                    механизм указания предпочтений пользователя среди множества .bb файлов предоставляющих одинаковый функционал 
                    или множества версий .bb.
                    </para>
                    <para>
                    Далее в разделе Метаданные, вы узнаете каким образом их можно настраивать.
                    </para>
                    <para>Стоит отметить, что в случае множества файлов, команда bitbake без использования параметра --buildfile использует  
   					<varname>псевдоним</varname>, который не является именем файла или чем-то еще. По умолчанию, .bb предоставляет
   					псевдонимы: имяпакета, имяпакета-версия, имяпакета-версия-ревизия.
                    </para>
                    <screen><prompt>$ </prompt>bitbake blah</screen>
                    <screen><prompt>$ </prompt>bitbake blah-1.0</screen>
                    <screen><prompt>$ </prompt>bitbake blah-1.0-r0</screen>
                    <screen><prompt>$ </prompt>bitbake -c clean blah</screen>
                    <screen><prompt>$ </prompt>bitbake virtual/whatever</screen>
                    <screen><prompt>$ </prompt>bitbake -c clean virtual/whatever</screen>
                </example>
                <example>
                    <title>Построение графа зависимостей</title>
                    <para>BitBake позволяет строить граф зависимостей используя dot синтаксис. Эти граф можно конвертировать 
                    в графическое представление используя приложение <application>dot</application> 
                    из пакета <ulink url="http://www.graphviz.org">graphviz</ulink>. 
                   В результате построения зависимострей в текущей директории появятся два файла, <emphasis>depends.dot</emphasis> 
                   содержащий информацию о зависимостях на уровне пакетов и <emphasis>task-depends.dot</emphasis> 
                   содержащий зависимости на уровне задач. Для исключения из графа стандартных зависимостей вы можете добавить 
                   <prompt>-I depend</prompt>.  Это позволяет создавать более короткие и понятные графы. К примеру таким образом
                   можно убрать из <varname>DEPENDS</varname> унаследованные классы (к примеру base.bbclass).
                   </para>
                    <screen><prompt>$ </prompt>bitbake -g blah</screen>
                    <screen><prompt>$ </prompt>bitbake -g -I virtual/whatever -I bloom blah</screen>
                </example>
                </para>
            </section>
            <section>
                <title>Специальные переменные</title>
                <para>Переменные влияющие на работу bitbake:</para>
                <section>
                    <title><varname>BB_NUMBER_THREADS</varname></title>
                    <para> Переменная указывает какое количество потоков bitbake может запускать одновременно (по умолчанию: 1).</para>
                </section>
            </section>
            <section>
                <title>Метаданные</title>
                <para>Как вы могли видеть из справки bitbake или из описания .bb файлов,переменная BBFILES 
                указывает где bitbake ищет .bb файлы. Эта переменная содержит список файлов разделенных пробелами, или их масок
                (к примеру recipes/*/*.bb).
                <example>
                    <title>Настройка BBFILES</title>
                    <programlisting><varname>BBFILES</varname> = "/path/to/bbfiles/*.bb"</programlisting>
                </example></para>
                <para>Что касается зависимостей, то ожидается что в .bb файле опеделена переменная <varname>DEPENDS</varname>,
                которая содержит список <quote>имен пакетов</quote> разделенных пробелами. Имена могут указываются в <varname>PN</varname>. 
                По умолчанию в качестве <varname>PN</varname> используется часть имени .bb файла.
                </para>
                <example>
                    <title>Зависимость от другого .bb файла</title>
                    <para>a.bb:
    <screen>PN = "package-a"
DEPENDS += "package-b"</screen>
                    </para>
                    <para>b.bb:
    <screen>PN = "package-b"</screen>
                    </para>
                </example>
                <example>
                    <title>Использование PROVIDES</title>
                    <para>Этот пример демонстрирует каким образом можно использовать переменную PROVIDES, 
                    для указания какую функциональность предоставляет .bb файл.</para>
                    <para>package1.bb:
    <screen>PROVIDES += "virtual/package"</screen>
                    </para>
                    <para>package2.bb:
    <screen>DEPENDS += "virtual/package"</screen>
                    </para>
                    <para>package3.bb:
    <screen>PROVIDES += "virtual/package"</screen>
                    </para>
                    <para>Как вы видите два разных .bb файла предоставляют аналогичную функциональность (virtual/package).  
                    Из-за этого требуется указание пользователем, какой из этих файлов будет использоваться.
              		</para>
                    <para>Указать что будет использоваться package1 можно добавив в  .conf файл следующую переменную со значением package1:
    <screen>PREFERRED_PROVIDER_virtual/package = "package1"</screen>
                    </para>
                </example>
                <example>
                    <title>Указание предпочитаемой версии</title>
                    <para>Когда имеется множество <quote>версий</quote> одного и того же пакета, bitbake по умолчанию
                    выбирает наиболее новую версию.  Если в .bb значение переменной <varname>DEFAULT_PREFERENCE</varname> 
                    меньше чем в других  .bb файлах (по умолчанию это 0), то он никогда не выбирается. Это позволяет разработчикам 
                    сопровождающим репозиторий .bb файлов указывать необходимую версию по умолчанию. Так же
                    это позволяет изменять предпочтения локально не взирая на предпочтения в репозитории.
                    </para>
                    <para>К примеру если первый файл .bb имеет имя <filename>a_1.1.bb</filename>, 
                    то переменная <varname>PN</varname> будет иметь значение <quote>a</quote>, 
                    а переменная <varname>PV</varname> будет иметь значение 1.1.</para>
                    <para>И если при этом имеется файл <filename>a_1.2.bb</filename>, то bitbake выберет 1.2 по умолчанию.  
                    Однако если определить в .conf файле, который обрабатыватся bitbake, ниже приведенную переменную,
                    то будет выбрана версия 1.1
    <screen>PREFERRED_VERSION_a = "1.1"</screen>
                    </para>
                </example>
                <example>
                    <title>Использование <quote>коллекций bb файлов</quote></title>
                    <para>Коллекции .bb файлов позволяют использовать множество репозиториев bb файлов содержащих
                    одинаковые пакеты. К примеру это позволяет использовать отдельную копию основного репозитория со своими изменениями, 
                    невошедшими в основной репозиторий. Для этого в .conf прописываем:</para>
                    <screen>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"</screen>
                </example>
            </section>
    </chapter>
</book>

