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

Adjust the Configuration File

Introduction​

This article explain how to create and edit the tcbuild.yml file of Torizoncore Builder tool to apply customizations to Torizon OS images.

Please refer to the following specific articles for additional resources:

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

Prerequisites​

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

Create 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 tcbuild.yaml file containing all possible configuration parameters accepted by the command. The configuration file is in YAML format, which is compatible with most modern code 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 are commented out with # 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.

Editing a Configuration File​

To enable a setting, you must uncomment the relevant line and all its parent levels by removing the leading #. A valid configuration file consists of three main sections, represented by top-level keys:

tcbuild.yaml
# Configuration file outline:
input:
  # Input section items (required).
customization:
  # Customization section items.
output:
  # Output section items (required).

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 you 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).

Simple Customization​

Check the following 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 in this example was defined via the toradex-feed property which allows you to set the desired attributes of the image to be downloaded. The buildcommand works with downloaded or remote images.

Notice also that there are 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. The file is 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

By running:

$ torizoncore-builder build

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

Variable Substitution​

To simplify configuration file usage when some values differ between build command invocations, we provide a feature commonly offered by command line shells: variable substitution.

If the feature is enabled, all occurrences of $VAR in string values are replaced by the corresponding value of the variable named VAR, which should be provided as part of the torizoncore-builder build command line invocation.

The following notations are allowed:

  • ${VAR}: Same as $VAR; when the variable is not set in command line, torizoncore-builder will issue a warning and assume the variable value is the empty string.
  • ${VAR:-default}: If VAR is not set or empty, use default as its value.
  • ${VAR-default}: If VAR is not set, use default as its value.
  • ${VAR:?error}: If VAR is not set or is empty, issue the message error and exit the tool
  • ${VAR?error}: If VAR is not set, issue the message error and exit the tool.
tip

The notation $$ can be used to insert a single literal $ sign within strings in the configuration file.

The following is an example of a configuration file with variable substitution:

output:
  easy-installer:
    bundle:
      compose-file: "${COMPOSE_FILE:?Path to the Docker Compose file is required}"
      username: "${REGISTRY_USER?Container registry username is required}"
      password: "${REGISTRY_PASS?Container registry password is required}"
      registry: "${REGISTRY_HOST:-docker.io}"

Without setting the COMPOSE_FILE variable in the torizoncore-builder build command, you will see:

Building image as per configuration file 'tcbuild.yaml'...

** Exiting due to user-defined error: Path to the Docker Compose file is required

To proceed with the build, you must provide the missing values. For example:

torizoncore-builder build \
  --set COMPOSE_FILE=docker-compose.yml \
  --set REGISTRY_USER=myusername \
  --set REGISTRY_PASS=mypassword

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 Customization Examples to learn practical customizations to Torizon OS images.

Send Feedback!