4 概念与参考

配置和使用 Toaster 需要理解一些概念，并了解基本命令。 本章介绍层来源、版本及 JSON 配置文件的概念，还简要介绍一些 Toaster 专用的 manage.py 命令。网上已有通用的 manage.py 文档， 本手册不打算提供完整的命令参考。

4 层来源

一般而言，“层来源”提供现有层的信息。这里关注的是可用于 Yocto 项目和 Toaster 的层。 本章介绍一种称为“层索引”的层来源。

层索引是一个 Web 应用，保存一组自定义层的信息。 OpenEmbedded 层索引就是一个例子，其公共实例位于 https://layers.openembedded.org/， Web 应用源码位于 https://git.yoctoproject.org/layerindex-web/。

将层来源接入 Toaster 后，Toaster 可以通过 REST API 查询它， 将层信息存入数据库，并展示给用户。用户可以直接在 Toaster 中查看信息和构建层， 不必手动克隆或编辑 BitBake 层配置文件 build/conf/bblayers.conf。

如果开发者社区需要经常构建许多自定义层，将层来源接入 Toaster 会很方便。 Toaster 实际上已经预配置了 OpenEmbedded 元数据索引。

备注

使用 Toaster 并不要求必须使用层来源；接入层来源是可选的。

4 配置和使用层来源

要使用自己的层来源，需要先搭建它，再接入 Toaster。 本节介绍与 Toaster 接入 OpenEmbedded 元数据索引类似的接入方式。

4 了解自己的层

使用层索引的第一步，是拥有开发者经常通过 Yocto 项目访问和构建的一组自定义层。 这些层必须已经存在，且你需要熟悉它们的位置。 配置用于接入这些层的 Web 应用时，需要使用这些信息。

层的一般介绍见 Yocto 项目概览与概念手册中的 Yocto Project 层模型。 创建层的方法见开发任务手册中的 理解和创建层。

4 配置 Toaster 以接入层索引

要让 Toaster 使用自己的层索引，必须将该 Web 应用托管在 Toaster 能连接的服务器上， 并向 Toaster 提供索引信息。本节介绍两种配置和使用自有层索引的方法。

前一节提到的 OpenEmbedded 元数据索引（https://layers.openembedded.org/）的代码位于 https://git.yoctoproject.org/layerindex-web/，可以用它作为创建自己层索引的基础。

4 使用管理界面

在浏览器中输入 Toaster 实例的 URL，并在末尾加上 /admin，即可访问管理界面。 例如，本地运行 Toaster 时使用：:

http://127.0.0.1:8000/admin

管理界面的 "Layer sources" 部分有 "Add layer source" 按钮。 点击并填写所需信息，确保层来源类型选择 "layerindex"。

4 使用 fixture 功能

通过 Django fixture 指定自定义 URL，可以覆盖默认层服务器。 创建或编辑 bitbake/lib/toaster.orm/fixtures/custom.xml， 将以下 Toaster 设置改为自定义 URL：

<?xml version="1.0" ?>
<django-objects version="1.0">
   <object model="orm.toastersetting" pk="100">
      <field name="name" type="CharField">CUSTOM_LAYERINDEX_SERVER</field>
      <field name="value" type="CharField">https://layers.my_organization.org/layerindex/branch/master/layers/</field>
   </object>
<django-objects>

第一次启动 Toaster，或者删除 toaster.sqlite 后重新启动时， 会从该层索引服务器向空数据库填入数据。

信息更新后，通过 Toaster 网页界面确认新层信息是否可用。 进入项目中的 "All compatible layers" 页面，应能看到来自该来源的层。

如果层索引服务器中的信息发生变化，运行以下命令刷新 Toaster 数据库：

$ bitbake/lib/toaster/manage.py lsupdates

如果 Toaster 能访问 API URL，就会显示正在更新层来源信息的消息。

4 版本

通过网页界面创建 Toaster 项目时，需要选择一个 "Release"。 在 Toaster 中，它指 OpenEmbedded 构建系统使用的一组层及一个 BitBake 版本。 Toaster 预配置了与 Yocto 项目发布分支对应的版本， 也可以根据需要修改、删除和创建版本。本节介绍相关背景。

4 预配置版本

Toaster 随附一组预配置版本，但也可以配置为使用任意版本。 例如，项目可能需要基于某个内置版本的特定提交构建， 或采用不同修订的 OpenEmbedded 和 BitBake。

Toaster 预配置了以下版本：

• Yocto Project 6.1 "Blacksail" 或 OpenEmbedded "Blacksail"： 使用 https://git.yoctoproject.org/poky/log/?h=blacksail 或 https://git.openembedded.org/openembedded-core/commit/?h=blacksail 中 blacksail 分支的最新提交进行构建。

• Yocto Project "Master" 或 OpenEmbedded "Master"： 使用正在积极开发的 master 分支最新提交，位于 https://git.yoctoproject.org/poky/log/ 或 https://git.openembedded.org/openembedded-core/log/。

• Local Yocto Project 或 Local OpenEmbedded： 使用运行 Toaster 的机器上本地 poky 或 openembedded-core 克隆的当前提交。

4 配置 Toaster

使用 Toaster 前，必须用默认内容初始化数据库。 以下各节介绍配置的不同方面。

4 配置工作流

bldcontrol/management/commands/checksettings.py 控制工作流配置。 数据库初始化流程如下：

1. 从 orm/fixtures/settings.xml 设置默认项目参数。

2. 如果安装了 poky，从 orm/fixtures/poky.xml 添加默认发行版和层； 否则从 orm/fixtures/oe-core.xml 添加。

3. 如果存在 orm/fixtures/custom.xml，加入其中的值。

4. 扫描层索引，并将其加入数据库。

完成后，Toaster 即已准备就绪。

4 定制预设数据

Toaster 的预设数据很容易定制。 可以创建 orm/fixtures/custom.xml，定制写入数据库的值。 定制内容以追加方式加载，可以扩展或完全替换已有值。

通过该文件可以修改默认项目的机器、发行版、镜像文件和层设置。 创建新项目时，也可以用它定义可供选择的其他项目版本。 例如，增加包含自定义层集合、发行版或其他本地及专有内容的选项。

此外，在 settings.xml 中定义以下部分，可以完全禁用 oe-core.xml 和 poky.xml 的内容。 如果自定义配置的版本或层少于默认 fixture 文件，这一选项尤其有用。

以下示例将 "name" 设为 "CUSTOM_XML_ONLY"，值设为 "True"：

<object model="orm.toastersetting" pk="99">
   <field type="CharField" name="name">CUSTOM_XML_ONLY</field>
   <field type="CharField" name="value">True</field>
</object>

4 理解 fixture 文件格式

本节概述 oe-core.xml、poky.xml 和 custom.xml 使用的文件格式。

以下各小节介绍 fixture 文件的各部分，并给出 XML 示例， 帮助理解格式和创建本地 custom.xml。

4 定义默认发行版及其他值

此部分定义新项目的默认发行版值，默认保留 Toaster Setting 中的第一条记录 "1"。 以下示例设置项目默认的 DISTRO：

<!-- Set the project default value for DISTRO -->
<object model="orm.toastersetting" pk="1">
   <field type="CharField" name="name">DEFCONF_DISTRO</field>
   <field type="CharField" name="value">poky</field>
</object>

可以添加其他 Toaster Setting 部分，覆盖其他默认项目值， 例如 settings.xml 提供的设置。也可以添加会进入 BitBake 环境的自定义值。 "pk" 必须唯一。按照约定，设置项目默认值的条目使用 "DEFCONF" 前缀。

4 定义 BitBake 版本

以下内容定义后续版本选项使用的 BitBake 版本：

<!-- Bitbake versions which correspond to the metadata release -->
<object model="orm.bitbakeversion" pk="1">
   <field type="CharField" name="name">blacksail</field>
   <field type="CharField" name="giturl">https://git.yoctoproject.org/poky</field>
   <field type="CharField" name="branch">blacksail</field>
   <field type="CharField" name="dirpath">bitbake</field>
</object>

4 定义版本

以下内容定义创建新项目时的版本选项：

<!-- Releases available -->
<object model="orm.release" pk="1">
   <field type="CharField" name="name">blacksail</field>
   <field type="CharField" name="description">Yocto Project 6.1 "Blacksail"</field>
   <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
   <field type="CharField" name="branch_name">blacksail</field>
   <field type="TextField" name="helptext">Toaster will run your builds using the tip of the <a href="https://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=blacksail">Yocto Project Blacksail branch</a>.</field>
</object>

"pk" 必须与上面对应的 BitBake 版本记录一致。

4 定义版本的默认层名称

以下内容定义每个版本的默认层：

<!-- Default project layers for each release -->
<object model="orm.releasedefaultlayer" pk="1">
   <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
   <field type="CharField" name="layer_name">openembedded-core</field>
</object>

上例的 'pk' 应从 "1" 开始递增，并保持唯一。 不同版本可以使用同一个层名称。

4 定义层

层定义最复杂。下面先定义每个层，再定义各版本使用的确切层版本。 每个层必须有一条 orm.layer 记录，以及一组 orm.layer_version 记录， 将该层与包含它的各个版本关联。通常所有版本都会包含该层。

<object model="orm.layer" pk="1">
   <field type="CharField" name="name">openembedded-core</field>
   <field type="CharField" name="layer_index_url"></field>
   <field type="CharField" name="vcs_url">https://git.yoctoproject.org/poky</field>
   <field type="CharField" name="vcs_web_url">https://git.yoctoproject.org/cgit/cgit.cgi/poky</field>
   <field type="CharField" name="vcs_web_tree_base_url">https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
   <field type="CharField" name="vcs_web_file_base_url">https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
</object>
<object model="orm.layer_version" pk="1">
   <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
   <field type="IntegerField" name="layer_source">0</field>
   <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
   <field type="CharField" name="branch">blacksail</field>
   <field type="CharField" name="dirpath">meta</field>
</object> <object model="orm.layer_version" pk="2">
   <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
   <field type="IntegerField" name="layer_source">0</field>
   <field rel="ManyToOneRel" to="orm.release" name="release">2</field>
   <field type="CharField" name="branch">HEAD</field>
   <field type="CharField" name="commit">HEAD</field>
   <field type="CharField" name="dirpath">meta</field>
</object>
<object model="orm.layer_version" pk="3">
   <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
   <field type="IntegerField" name="layer_source">0</field>
   <field rel="ManyToOneRel" to="orm.release" name="release">3</field>
   <field type="CharField" name="branch">master</field>
   <field type="CharField" name="dirpath">meta</field>
</object>

层的 "pk" 必须唯一，通常从 "1" 开始。 层版本的 "pk" 也必须在所有层之间唯一，通常同样从 "1" 开始。

4 远程监控 Toaster

Toaster 提供 API，允许远程管理应用以机器间通信的方式， 直接查询 Toaster 服务器及其构建的状态。 该 API 使用 REST 接口传输 JSON。 例如，可以通过受支持的常见 HTTP 端口监控容器内的构建， 方便地访问容器中的 Toaster 服务器。 直接使用 JSON API，就无需解析面向用户的网页显示内容。

4 健康检查

使用远程监控前，应先进行健康检查。 通过以下调用探测 Toaster 服务器是否仍在运行：:

http://host:port/health

请提供 host 和 port 的实际值。服务器正常时，会返回以下 HTML：

<!DOCTYPE html>
<html lang="en">
   <head><title>Toaster Health</title></head>
   <body>Ok</body>
</html>

4 查询正在进行的构建状态

有时需要了解正在进行的构建状态。 使用以下调用获取尚未完成的构建状态：:

http://host:port/toastergui/api/building

请提供 host 和 port 的实际值。返回的 JSON 列出所有正在进行的构建， 包括各构建启动至今的秒数，以及克隆、解析和任务执行的进度。 示例输出如下：

{"count": 1,
 "building": [
   {"machine": "beaglebone",
     "seconds": "463.869",
     "task": "927:2384",
     "distro": "poky",
     "clone": "1:1",
     "id": 2,
     "start": "2017-09-22T09:31:44.887Z",
     "name": "20170922093200",
     "parse": "818:818",
     "project": "my_rocko",
     "target": "core-image-minimal"
   }]
}

实际返回的 JSON 为单行，此处为便于阅读手动换行。

4 查询已完成的构建状态

构建完成后，可以使用以下调用获取状态：:

http://host:port/toastergui/api/builds

请提供 host 和 port 的实际值。返回的 JSON 列出所有已完成的构建及其摘要信息。 示例输出如下：

{"count": 1,
 "builds": [
   {"distro": "poky",
      "errors": 0,
      "machine": "beaglebone",
      "project": "my_rocko",
      "stop": "2017-09-22T09:26:36.017Z",
      "target": "quilt-native",
      "seconds": "78.193",
      "outcome": "Succeeded",
      "id": 1,
      "start": "2017-09-22T09:25:17.824Z",
      "warnings": 1,
      "name": "20170922092618"
   }]
}

实际返回的 JSON 为单行，此处为便于阅读手动换行。

4 查询指定构建的状态

要查询某次特定构建的状态，使用以下调用：:

http://host:port/toastergui/api/build/ID

请提供 host、port 和 ID 的实际值。ID 可从已完成构建的查询结果中获得， 详见 查询已完成的构建状态。

返回的 JSON 列出该构建的详细信息及摘要，示例如下：

{"build":
   {"distro": "poky",
    "errors": 0,
    "machine": "beaglebone",
    "project": "my_rocko",
    "stop": "2017-09-22T09:26:36.017Z",
    "target": "quilt-native",
    "seconds": "78.193",
    "outcome": "Succeeded",
    "id": 1,
    "start": "2017-09-22T09:25:17.824Z",
    "warnings": 1,
    "name": "20170922092618",
    "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
   }
}

实际返回的 JSON 为单行，此处为便于阅读手动换行。

4 实用命令

除了网页界面和启停脚本，还可以通过 manage.py 管理脚本执行命令行操作。 通用文档见 Django 网站。 Toaster 还提供若干专用的 manage.py 命令，用于控制配置和后端任务。 这些命令位于 Source Directory （例如 poky）中的 bitbake/lib/manage.py。本节介绍这些命令。

备注

• 使用默认配置时，执行 manage.py 命令必须将工作目录设为 Build Directory，这样 Toaster 才能找到其中的 toaster.sqlite。

• 对于非默认数据库配置，可以从其他目录运行 manage.py， 前提是 toastermain/settings.py 已指向正确的数据库后端。

4.5.1 buildslist

buildslist 列出 Toaster 记录的全部构建。调用方式如下：

$ bitbake/lib/toaster/manage.py buildslist

命令返回当前数据库中的构建列表，包含数字形式的标识符。

使用 builddelete 之前， 需要先运行 buildslist，确定数据库中已有构建的 ID。 以下示例假设使用默认仓库名和 Build Directory 名称：

$ cd poky/build
$ python ../bitbake/lib/toaster/manage.py buildslist

如果数据库中只有一次构建，buildslist 会返回类似以下内容：:

1: qemux86 poky core-image-minimal

4.5.2 builddelete

builddelete 删除与某次构建关联的数据。调用方式如下：

$ bitbake/lib/toaster/manage.py builddelete build_id

它会删除指定 build_id 的全部构建数据，适合清理数据库中的旧数据和无用数据。

执行之前，需要通过 buildslist 获取构建对应的 ID。

4.5.3 perf

perf 测量 Toaster 性能。调用方式如下：

$ bitbake/lib/toaster/manage.py perf

此命令执行基本检查并返回页面加载时间，帮助识别性能问题。

4.5.4 checksettings

checksettings 验证现有 Toaster 设置。调用方式如下：

$ bitbake/lib/toaster/manage.py checksettings

Toaster 根据数据库中的设置配置构建任务。 此命令验证数据库设置是否有效，即是否包含启动构建所需的最基本信息。

要让 checksettings 正常工作，数据库必须正确建立且没有已有数据。 可以运行以下命令确保数据库准备就绪：

$ bitbake/lib/toaster/manage.py syncdb
$ bitbake/lib/toaster/manage.py migrate orm
$ bitbake/lib/toaster/manage.py migrate bldcontrol

之后即可运行 checksettings。

4.5.5 runbuilds

runbuilds 启动已调度的构建。调用方式如下：

$ bitbake/lib/toaster/manage.py runbuilds

它检查数据库中是否存在已调度的构建，并按调度启动。 命令在构建启动后、完成前返回。构建完成时，Toaster 日志接口会记录并更新数据库。