Templating Context¶
As explained in Understanding the SBXG Library, some files are to be templated by SBXG. Namely: the boot scripts and images configurations. The underlying templating engine is Jinja2. Templating engines uses what is called a templating context: it is the dataset used to output a meaningful result.
Since users are expected to create your own library to tweak SBXG to fit their needs, having a clear documentation of this templating context is mandatory. It can be seen as a stable interface between SBXG and its users.
Currently, no promise is made of a stable interface
As we are still in early development, this may change.
Notion of canonical names
Later in this document, we will mention canonical names. These are litteral strings derived from the names of files that are parts of the SBXG library. Canonical names are expected to be used by programming languages, such as GNU make. Which implies that it shall be get rid of unexpected characters (dots, dashes, spaces, …). In the canonical form, all the unwanted characters are replaced with underscores.
Top-level entries¶
The templating context will always contain the following top-level entries.
Note that they may be set to None if not available, but it is guaranteed
that these keys will exist.
| Name | Type | Description |
|---|---|---|
| top_build_dir | string |
Where components will be built |
| toolchain | Toolchain |
Description of the toolchain |
| downloads | list<Download> |
List of items to be downloaded |
| linuxes | list<Item> |
List of the Linux kernels to be built |
| uboots | list<Item> |
List of the bootloaders to be built |
| xens | list<Item> |
List of the Xen hypervisors to be built |
| genimage | Genimage |
Description of the genimage tool |
| board | Board |
Description of the board |
The types mentioned in this table will be detailed in the next sections.
Toolchain data structure¶
The Toolchain type is composed of following entries that were written in
the YAML file that describes the toolchain. See The toolchains/ subdirectory for
details.
Download data structure¶
It should be no surprise that the build system generated by SBXG will attempt
to download the sources of the components to be built. What falls in the
scope of a Download object is compressed tar archives containing sources.
This includes Linux, U-Boot, Xen and genimage. A download receives a name,
that uniquely identifies it amongs others. It also allows components to be
built to depend on a download, by referring to its name.
| Name | Description |
|---|---|
| name | Canonical name of the download |
| url | URL where to fetch the component |
| archive | Filename of the component to be downloaded |
Item data structure¶
An Item describes either a Linux kernel, a U-Boot bootloader or a Xen
hypervisor. All entries in an Item are of type string. It is composed
of the entries written in the YAML file that describes these components. See
The sources/ subdirectory for details. In addition to these fields, the following
entries are guaranteed to exist:
| Name | Description |
|---|---|
| config | Full path to the associated Kconfig file |
| name | Canonical name of the component |
| download | Name of the associated download information |
Genimage data structure¶
The Genimage type is composed of the entries written in the YAML file that
describes genimage. See The sources/ subdirectory for details.
Board data structure¶
The Board type is a subset of the elements described in The boards/ subdirectory,
which is defined by the following entries:
- linux_dtb;
- linux_image;
- uboot_image;
- boot_script;
- disk_image;
- root;
- bootargs.
It comes with the following extraneous string entries:
| Name | Description |
|---|---|
| rootfs_url | The URL where the rootfs resides |
| rootfs_path | Filename of the rootfs after download |