Bolt‑Based Web Application

To build a Bolt‑based web application, you will need the following:

• Bolt Tools
• App package configuration
• Certificates for signing the app bundle

1. Bolt Tools

Install and set up bolt-tools on your system by following the instructions in the repository:

Bolt Tools provides the utilities required to package and sign your Bolt applications.

2. App Package Configuration

The app package configuration defines the entry point, dependencies, permissions, and other metadata required for building the Bolt package.

2.1 Key Fields:

• Entry Point
  For a web application, the entry point should be the URL that the WPE WebKit browser should load.

  Example: "--url=https://lightningjs.io/tmdb/#splash"

• Dependencies:
  Specify the runtime and base Bolt packages your app depends on.
  For web apps, you must include the WPE browser package and its appropriate version.

  Example: "com.rdkcentral.wpe-rdk": "0.1.0"
  

• Permissions:
  Permissions required by the container, such as:
  • internet
  • thunder
  • firebolt
  • rialto

Sample App Configuration (JSON)

{
  "id": "com.rdkcentral.appName",
  "version": "0.1.0",
  "versionName": "develop",
  "name": "tmdb",
  "packageType": "application",
  "entryPoint": "--url=https://lightningjs.io/tmdb/#splash",
  "dependencies": {
    "com.rdkcentral.wpe-rdk": "0.1.0"
  },
  "permissions": [
    "urn:rdk:permission:internet",
    "urn:rdk:permission:firebolt",
    "urn:rdk:permission:thunder",
    "urn:rdk:permission:rialto"
  ],
  "configuration": {}
}

3. Creating a Bolt Package

To package an HTML/Lightning app into a Bolt bundle, you need:

1. A JSON configuration file (com.rdkcentral.app_name.json)
2. A rootfs layer in .tgz format

For HTML/Lightning applications, the rootfs layer can be an empty .tgz file, since the app is launched via a browser using a URL.

Steps

1. Create an empty .tgz file, e.g.:

   empty.tgz
   

2. Create your App Package configuration JSON file.
3. Run the Bolt pack command:

   bolt pack com.rdkcentral.app_name.json empty.tgz
   

4. The command will generate:

   com.rdkcentral.app_name+<version>.bolt
   

   This is the Bolt package to be installed on the platform.

Bolt-based Native Applications

This page describes the process for creating and building native Bolt applications within the RDK ecosystem. The meta-bolt-youtube repository serves as the canonical reference implementation throughout this article.

See also: meta-bolt-distro | bolt-tools

Overview:

A native Bolt application is a self-contained, application packaged as `.bolt` . Each application is maintained in its own Yocto meta-layer repository and follows a shared set of conventions across all RDK Bolt projects.

The overall workflow is:

1.  Create a new application repository following the standard naming and layout.
2. Declare all build-time dependencies in manifests/deps.xml.
3. Add or reuse Yocto image recipes and native app recipes.
4. Define package configs that instruct the Bolt tool how to assemble the final package.
5. Source the build environment and run the Bolt make command.

2. Repository Setup

2.1 Naming Convention

All RDK Bolt application repositories follow this naming pattern:

meta-bolt-<app_name>

Examples:

• meta-bolt-youtube
• meta-bolt-amazon-prime
• meta-bolt-myapplication

2.2 Repository Structure

A new meta-bolt repository is expected to contain the following top-level layout:

    meta-bolt-<app_name>/
    ├── README.md
    ├── CONTRIBUTING.md
    ├── LICENSE
    ├── COPYING
    ├── CHANGELOG.md
    ├── NOTICE
    ├── manifests/          # dependency declarations (see Section 3)
    ├── package-configs/    # Bolt package configuration JSON files (see Section 6)
    ├── recipes-core/       # image recipes (see Section 4)
    ├── recipes-devtools/   # host-tool recipes
    ├── recipes-extended/   # native app recipes and bbappend files (see Section 5)
    ├── conf/               # Yocto layer configuration
    └── setup-environment   # reusable environment setup script (see Section 7)

3. Dependency Management

3.1 manifests Folder

The manifests folder is the central location for declaring all components that the build system must fetch and integrate before building the native application.

3.2 deps.xml Format

The deps.xml file inside the manifests folder acts as a dependency resolver for the Bolt application build. It declares:

• Required repositories and their remote locations
• Branch names or commit references to pin versions
• Build-time dependency relationships between components

Typical entries in deps.xml cover:

• The base Bolt distro layer
• Core runtime components
• Application-specific libraries
• Development tool layers

Reference: deps.xml

4. Bolt Image Recipe

4.1 Purpose

An image recipe is a BitBake (.bb) file placed under recipes-core/images/. It defines the full contents of the root filesystem that will be assembled into the final Bolt package, including which packages, binaries, libraries, and supporting components are installed.

4.2 What to Include

The image recipe should declare all runtime dependencies of the native application so that the resulting Bolt package is complete and self-contained.

The following image recipes in meta-bolt-youtube can be used as templates:

• recipes-core/images/cobalt-bolt-image.bb
• recipes-core/images/nplb-bolt-image.bb

5. Native Application Recipes

Native application recipes are BitBake recipes that build the application binaries and libraries included in the final package. They can be sourced in one of two ways:

5.1 Reuse from Dependent Layers

If an existing recipe for the native application already exists in one of the meta-layers declared in manifests/deps.xml, that recipe can be consumed directly without duplication.

5.2 Adding New Recipes

When a suitable recipe does not exist upstream, new .bb recipe files or .bbappend overlay files can be added under the local recipes-extended tree:

recipes-extended/<app_or_component>/

Keeping customisations in recipes-extended isolates them from upstream changes and makes future maintenance easier.

6. Package Configuration

The package-configs directory holds JSON configuration files that the Bolt tool reads to determine how to build a target image and assemble the final Bolt package.

There are two distinct config file types for each application:

6.1 <app_name>.bolt.json

This file is the primary Bolt build configuration. It instructs the Bolt tool on:

• Which Yocto image target to build
• Which metadata files to include in the final Bolt package

Reference examples in meta-bolt-youtube:

• package-configs/cobalt.bolt.json
• package-configs/youtube.bolt.json

6.2 com.rdkcentral.<app_name>.json

This file contains the native application package metadata that is shipped inside the Bolt package. At runtime, the on-device application management service reads this file to determine:

• Which dependent Bolt packages (such as base and runtime) must be mounted before launch
• Which environment variables and configuration must be exported into the app container.
• How the application is to be started within the Bolt runtime model.

Reference examples in meta-bolt-youtube:

• package-configs/com.rdkcentral.cobalt.json
• package-configs/com.rdkcentral.youtube.json

7. Setup Environment

The setup-environment and repo-sync scripts provided in meta-bolt-youtube are intentionally generic and designed to be reused in new Bolt application repositories with little to no
modification.

To adapt them for a new repository:

1. Copy setup-environment and repo-sync into the root of the new meta-bolt-<app_name> repository.
2. Ensure the dependency layout declared in manifests/deps.xml aligns with any path assumptions made by the scripts.
3. Apply only minimal repo-specific changes where required, such as updating default repository names or local build directory paths.

Reusing these scripts keeps the bootstrap and workspace initialization process consistent across all native Bolt application projects.

Build Commands:

  build/bolts/

source setup-environment
mkdir bolts/ # inside your build folder
cp <copy your dependent bolt package for eg. base.bolt> bolts/
bitbake bolt-env && hash bolt #build bolt tools for your build setup
bolt make <app_name>

The bolt make command reads the corresponding <app_name>.bolt.json config, triggers the Yocto image build for the declared target, and packages all required content into the final Bolt package.

References

• meta-bolt-youtube     : https://github.com/rdkcentral/meta-bolt-youtube 
• meta-bolt-distro      : https://github.com/rdkcentral/meta-bolt-distro 
• bolt-tools            : https://github.com/rdkcentral/bolt-tools