Web Application

To build a web application package, 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 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 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 the Package

To package an HTML/Lightning app into a DAC App 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 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.

Native Applications

A native application package( also known as BOLT package ) 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 such projects. This page describes the process for creating and building native app packages within the RDK ecosystem. The meta-bolt-youtube repository serves as the canonical reference implementation throughout this article.

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.

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

1. Repository Setup

Naming Convention

All RDK application repositories follow this naming pattern:

meta-bolt-<app_name>

Examples:

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

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)

2. Dependency Management

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.

deps.xml Format

The deps.xml file inside the manifests folder acts as a dependency resolver for the 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

3. Bolt Image Recipe

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.

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

4. 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:

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.

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.

5. 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:

<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

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

6. Setup Environment

The setup-environment and repo-sync scripts provided in meta-bolt-youtube are intentionally generic and designed to be reused in new DAC 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