Skip to main content
Version: Torizon OS 7.x.y

TorizonCore Builder Tool “build” command

Introduction​

The TorizonCore Builder Tool provides a series of commands that allow the quick and easy customization of a Toradex Easy Installer image for deployment and provisioning. Most commands allow for the customization of very specific items, meaning that the full customization of an image would commonly require the execution of multiple such commands. This gives a great deal of flexibility to the user but it also makes the utilization of the tool more difficult. To simplify its usage, the tool provides the build command that allows the full customization of an image as a single step.

This article complies with the Typographic Conventions for the Toradex Documentation.

Prerequisites​

This article assumes that the tool has been installed as described in Installing TorizonCore Builder.

For a quick hands-on introduction to the tool, go over the User Guide. For more details about the build command and on the contents of the configuration file that controls its behavior, see the Detailed manual. They are both accessible through the tabs below.

General Procedure​

In order to leverage the build command you will basically need to:

  • Create a configuration file with the desired settings (the tool can even help you with that);
  • Make sure all local artifacts possibly referenced by the configuration file are available;
  • Run the command.

Creating a Configuration File​

The easiest and thus recommended way for creating an initial configuration file is by running:

$ torizoncore-builder build --create-template

The previous command will create a file named tcbuild.yaml containing all possible configuration parameters accepted by the command.

The configuration file is in a standard YAML format which should be recognized by most modern programming editors. Any other name can be chosen for the file, but tcbuild.yaml is the name that the build command will expect by default when running in build mode. Most parameters in the generated file will be commented out which can be seen by the # character at the beginning of each line. Lines having the characters >> are just explaining the contents of the file and should be left as-is or removed if desired.

The contents of the file are organized in a tree structure where the leaves are configurable properties. In order to set a certain property you need to make sure all its parent properties are also uncommented (by removing the # character). For example, below we have a short stretch of the generated configuration file:

# >> The customization section defines the modifications to be applied to get
# >> the desired output image.
# customization:
  # >> Splash screen:
  # splash-screen: custom-splash-screen.png

If you wanted to set a splash screen, all you would need to do is to uncomment (and edit) the splash-screen property and its parent properties, in this case the one named customization, thus producing:

# >> The customization section defines the modifications to be applied to get
# >> the desired output image.
customization:
  # >> Splash screen:
  splash-screen: files/my-splash-screen.png

Also, the file files/my-splash-screen.png should be available before running the build command.

info

All paths to files or directories in the configuration file are relative to the working directory of the tool, which is set when the torizoncore-builder alias is created (see the prerequisites section). Moreover, since TorizonCore Builder runs in a container, no paths above the working directory will be accessible by the tool (e.g. ../my-splash-screen.png would not work).

In the following sections we provide some examples that show how easy it is to create a custom image by employing the build command.

Example: Minimal Configuration File​

A minimal configuration file has to specify at least one input and one output. Below we assume that the input is a previously downloaded Toradex Easy Installer image that is stored in a directory called images relative to the working directory (set by the alias of the tool).

# Sample configuration file:
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
caution

As a general rule, the input image to be customized MUST NOT contain bundled container images – when choosing an image to download, e.g. from Toradex Easy Installer - OS and Demo Images be sure to download an image without evaluation containers.

The directory structure of such a "project" would look like this:

.
├── images
│   └── torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar
└── tcbuild.yaml

To run the tool one would simply execute:

$ torizoncore-builder build

Once the build process finishes, the custom Easy Installer image would be present in a directory called torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM.

Example: Fetching Remote Images​

The input to the tool can be specified in different ways which are described in the Detailed Manual and they are independent of the customization being performed.

caution

Notice that not all images allow the customization of every possible property that the "build" command provides; e.g. older images may not allow that kernel modules to be built from source and deployed with the image.

In the sample configuration file below, we directly download an image from Toradex's artifacts server:

# Sample configuration file specifying a remote:
input:
  easy-installer:
    remote: "https://artifacts.toradex.com:443/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/1/colibri-imx6/torizon-upstream/torizon-core-docker/oedeploy/torizon-core-docker-colibri-imx6-Tezi_5.1.0%2Bbuild.1.tar;sha256sum=5d11dc0b6be688f6a7d159280e9bca15e26bc58732724e3e1dd66b0d0a6ada08"

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-Tezi_5.1.0+build.1.CUSTOM
    name: "My customized image"

Notice the presence of the sha256sum parameter which can be used to ensure that the downloaded file has a certain SHA-256 checksum – the tool will stop if the actual file checksum does not match that value (the Detailed Manual gives more information about how a remote location can be specified).

This "project" would simply contain the tcbuild.yaml file and by running:

$ torizoncore-builder build

You would get a custom Easy Installer image in the directory torizon-core-docker-colibri-imx6-Tezi_5.1.0+build.1.CUSTOM. The only item actually customized in that image is its name which is shown by the Toradex Easy Installer tool in its UI.

Example: Simple Customization​

Here we have a configuration file where multiple items are being customized:

# Sample configuration file:
input:
  easy-installer:
    toradex-feed:
      version: "5.3.0"
      release: monthly
      machine: colibri-imx6
      distro: torizon-upstream
      variant: torizon-core-docker
      build-number: "12"
      build-date: "202105"

customization:
  splash-screen: custom/splash-screen.png
  filesystem:
     - changes1/
     - changes2/
  kernel:
    arguments:
      - key1=val1
      - key2=val2

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-custom
    name: "My customized image"
    description: "My customized image (description)"
    licence: custom/licence.html
    release-notes: custom/release-notes.html

The input here was defined via the toradex-feed property which allows you to set the desired attributes of the image to be downloaded. Notice also that we are applying two groups of changes to the filesystem which are listed under the customization/filesystem property. These changes could have been extracted from a live device, for example, by utilizing the torizoncore-builder isolate command. We are also setting custom kernel arguments and requesting the use of specific licence and release-notes files.

The directory structure of such a "project" could be like this:

.
├── changes1
│   └── usr
│       └── etc
│           ├── test1.txt
│           └── timezone
├── changes2
│   └── usr
│       └── etc
│           └── test2.txt
├── custom
│   ├── licence.html
│   ├── release-notes.html
│   └── splash-screen.png
└── tcbuild.yaml

Again, by simply running:

$ torizoncore-builder build

You would get your custom Easy Installer image in the directory torizon-core-docker-colibri-imx6-custom.

Example: Device-tree Customization​

In this sample configuration file we customize the device-tree to be deployed with an image:

# Sample configuration:
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar

customization:
  device-tree:
    include-dirs:
      - device-trees/include/
    custom: device-trees/dts-arm32/imx6dl-colibri-eval-v3.dts
    overlays:
      add:
        - device-trees/overlays/colibri-imx6_hdmi_overlay.dts
        - device-trees/overlays/colibri-imx6_atmel-mxt-connector_overlay.dts

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-custom-dt

Usually one would create a device-tree (DT) source file and supply it to the tool via the customization/device-tree/custom property. Another, usually simpler, option is to leverage the device-tree source files provided by Toradex along with DT overlays that override the relevant parts of the tree – this was the approach taken on the example. To get the source code of the Toradex supplied device-tree files (including overlays), one could use the torizoncore-builder dt checkout command. A possibly better solution if you use Git for version control would be to manage these external device-trees through the Git submodule facility.

The directory structure for this "project" would look like this:

.
├── device-trees
│   ├── dts-arm32
│   │   ├── imx6dl-colibri-eval-v3.dts
│   ├── include
│   │   └── dt-bindings
│   │       ├── ...
│   ├── overlays
│   │   ├── ...
│   │   ├── colibri-imx6_atmel-mxt-adapter_overlay.dts
│   │   ├── colibri-imx6_atmel-mxt-connector_overlay.dts
│   │   ├── colibri-imx6_hdmi_overlay.dts
│   │   ├── colibri-imx6_parallel-rgb-lvds_overlay.dts
│   │   ├── colibri-imx6_parallel-rgb_overlay.dts
│   │   ├── ...
│   │   └── Makefile
│   └── README.md
├── images
│   └── torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar
└── tcbuild.yaml

The device-trees directory subtree might have been obtained via the torizoncore-builder dt checkout command, as mentioned.

Again, through the execution of:

$ torizoncore-builder build

You would get a custom Easy Installer image in the directory torizon-core-docker-colibri-imx6-custom-dt.

Example: Building Kernel Modules​

The build command allows you to build and install kernel modules into the deployed OS image. This is demonstrated in this configuration file:

# Sample configuration: build virtual touchscreen into the image
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar

customization:
  kernel:
    modules:
      - source-dir: virtual_touchscreen/
        autoload: no

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-vt

In this case, by running:

$ torizoncore-builder build

The tool would build the kernel module from the sources located in directory virtual_touchscreen and create a custom Easy Installer image in the directory torizon-core-docker-colibri-imx6-vt.

For more general information about the subject, please refer to Building External Kernel Modules With Torizon.

Example: Capturing Configuration Changes in the Target Device​

If you performed configuration changes on Torizon OS in the SoM, this command is necessary to capture them. To capture the configuration changes made in the target device, run the command below - remember to replace the remote-host IP, user name and password to match your target device information:

$ torizoncore-builder isolate --remote-host 192.168.1.10 --remote-username torizon --remote-password torizon --changes-directory changes1

Then to include these changes in the image, use the customization below:

# Sample configuration: capturing changes made in a target device
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar

customization:
  filesystem:
     - changes1/

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-cg

As before, by running:

$ torizoncore-builder build

You will get a custom Easy Installer image in the directory torizon-core-docker-colibri-imx6-cg.

See the Capturing Changes in the Configuration of a Board on Torizon OS article for detailed instructions.

Also, for more details on how the isolate command works, please check the isolate command in the commands manual.

Example: Bundling Application Container Images​

The build command also simplifies the process of bundling container images into an installer image. It is ideal for generating the image to be used during production programming and provisioning multiple devices.

If you want to install both the OS and application during an update, you should not use the Bundling feature. Instead, you should use the synchronous update feature of our Torizon Cloud.

A sample configuration file leveraging that feature is this:

# Sample configuration file:
input:
  easy-installer:
    remote: "https://artifacts.toradex.com:443/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/1/colibri-imx6/torizon-upstream/torizon-core-docker/oedeploy/torizon-core-docker-colibri-imx6-Tezi_5.1.0%2Bbuild.1.tar;sha256sum=5d11dc0b6be688f6a7d159280e9bca15e26bc58732724e3e1dd66b0d0a6ada08"

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-with-containers
    name: "My customized image with container images"
    bundle:
      compose-file: custom/docker-compose.yml

With such an input, the tool will fetch the container images referenced by the specified docker-compose.yml file and combine them with the installer image. If you don't want the tool to download the images every time the build command is run, you can download them beforehand via the torizoncore-builder bundle command which will fetch the images and store them into a directory which can then be supplied to the tool via the output/easy-installer/bundle/dir property (in place of the output/easy-installer/bundle/compose-file as in the example).

As before, by running:

$ torizoncore-builder build

You will get a custom Easy Installer image in the directory torizon-core-docker-colibri-imx6-with-containers.

caution

Due to the way TorizonCore Builder works, a directory called certs will be created in the working directory when build is run with the compose-file property. This is a known issue that will be solved in a future version of the tool.

Example: Provisioning an Image​

There are cases where you want to customize an image for automatic provisioning during production programming, so your devices can be ready for using with our Torizon Cloud. The devices will automatically be registered for using our secure remote or offline update, devices monitoring, and the new features to be released.

For this, you should get the provisioning data and apply in the configuration file.

You’ll need the credentialis.zip file for the account to which you want to provision devices. Since credentials access and other sensitive data are involved, this step should be run by your system admin or those with proper access to such information.

There are two types of provisioning data:

  • Shared-Data: This type of provisioning data is used for provisioning a device for offline and online updates. This data is not security-sensitive. In our system, we distribute the data as a tarball that contains the data.
  • Online-Data: This type of provisioning data is used only in provisioning for online updates. This data is security-sensitive and should be handled carefully. In our system we distribute the data as a base64 encoded string.

In order to get either provisioning data, use the platform provisioning-data command can be used to fetch both types of provisioning data:

$ torizoncore-builder platform provisioning-data --credentials credentials.zip --shared-data shared-data.tar.gz --online-data DEFAULT

The command will then produce a tarball containing the shared-data and output the string that is the online-data. This data can then be stored for future provisioning use. For a detailed guide on the usage of this command please see the specific section in the commands manual

Now that you have obtained your provisioning data, you need to apply it. The idea here is that you want to create a single Torizon OS image that, when flashed to multiple devices, will allow each device to provision itself automatically.

A sample configuration file for applying the provisioning data is this:

input:
  easy-installer:
    local: <INPUT_IMAGE>

output:
  easy-installer:
    local: <OUTPUT IMAGE>
    provisioning:
      mode: "online"
      shared-data: <SHARED-DATA TARBALL>
      online-data: <ONLINE-DATA STRING>
      hibernated: <true|false>
caution

Recall that the online-data string is sensitive information. You’ll most likely want to make use of variable substitution, rather than inserting this string in plain text in your yaml file.

For more details see the provisioning property under the Output section of the build command’s yaml file schema.

Example: Variable Substitution​

A feature that can be especially useful in CI scripts is called variable substitution which allows the replacement of property values (or parts of them) based on parameters passed on the command-line of the tool. The following configuration file employs that feature:

# Sample configuration file:
input:
  easy-installer:
    remote: "https://artifacts.toradex.com:443/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/1/colibri-imx6/torizon-upstream/torizon-core-docker/oedeploy/torizon-core-docker-colibri-imx6-Tezi_5.1.0%2Bbuild.1.tar;sha256sum=5d11dc0b6be688f6a7d159280e9bca15e26bc58732724e3e1dd66b0d0a6ada08"

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-with-containers
    name: "${IMAGE_NAME-Default image name}"
    description: "${IMAGE_DESC?Please provide a description for this image}"
    bundle:
      compose-file: custom/docker-compose.yml

The value of property output/easy-installer/name in the example is set to the value of variable IMAGE_NAME or to "Default image name" when the variable is not set. The property output/easy-installer/description depends on IMAGE_DESC which is required and if not set will cause the tool to exit showing the specified message. Running the build command by itself would fail like this:

$ torizoncore-builder build
Building image as per configuration file 'tcbuild.yaml'...

** Exiting due to user-defined error: Please provide a description for this image

In order to successfully build an image with the previous configuration file (using the default value for IMAGE_NAME), one could run:

$ torizoncore-builder build --set IMAGE_DESC="This is the required description"

For more information on the notation for replacing variables in the configuration file, please refer to the Detailed Manual.

Next Steps​

We recommend that you take a look at the Detailed Manual tab at the beginning of the page to get a better understanding of the ideas behind the build command.



Send Feedback!