Skip to main content
Version: 6

How to Use Web Browser (Linux)


This page has not been fully updated to reflect the changes made in Toradex Linux BSP 6. Some information may still apply to Toradex Linux BSP 6 configurations. If you encounter issues, please Send Feedback.
If you are using version 5 LTS, please visit the 5 LTS version documentation.


WPE WebKit (former WebKitForWayland), is the official webKit port for embedded platforms. It aims to allow embedded developers to create simple and performant systems based on Web platform technologies. It is designed with hardware acceleration in mind, leveraging common 3D graphics APIs for best performance.

For further information you can check:

Also, Chromium support is provided by the 3rd party layer meta-browser.


If you are looking for information on how to use web browsers on TorizonCore, refer to Web Browser / Kiosk Mode with TorizonCore.


Before proceeding with this article, make sure you have a good understanding of the process described at Build a Reference Image with Yocto Project/OpenEmbedded article.

Build Machine Requirements

Minimum specifications:

  • 60GB of free disk space;
  • 32 bits host machine;
  • 4GB of RAM.

Recommended specifications:

  • Multi-core machine;
  • 64 bits host machine;
  • 8GB or more of RAM.

The following Linux distributions are supported and you must use one of them on your development PC to build our BSPs: Detailed Supported Distros.

Build Dependencies

You must install the Yocto Project dependencies listed at required packages on the host PC.

First Steps

For more information on how to use Yocto Project in your project, you can refer to the following articles:

For your first build, you can also refer to Yocto Project documentation.

Cog Browser

Add Cog/WPE using Yocto Project

The first step is to setup Yocto build environment, as described in Build a Reference Image with Yocto Project/OpenEmbedded.


Considering you already have set up the Yocto Project environment, the variable LAYERDIR contains the path to the layers directory, and the variable BUILDDIR, the path to the build directory.

Then go to the LAYERDIR and clone the Meta-Webkit repository. Make sure to checkout the Dunfell branch, since BSP 5 is based on the Dunfell Yocto branch.

$ cd ${LAYERDIR}

$ git clone -b dunfell

It's important to have, in the layers directory, the QT5 layer, which you can find in the Qt5 layers Github.

$ cd ${LAYERDIR}

$ git clone

After these steps, you will have to add the layers into the bblayers.conf.

$ cd ${BUILD_DIR}
$ echo 'BBLAYERS += " ${TOPDIR}/../layers/meta-webkit"' >> conf/bblayers.conf

The next step is to change the local.conf file to add the correct package to the output image. So add the following lines at the end of the local.conf file.

IMAGE_INSTALL_append = " wpewebkit cog imx-gst1.0-plugin"                                                                     
PREFERRED_PROVIDER_virtual/wpebackend = "wpebackend-fdo"

Don't forget to select the specific machine to target the build with also in the local.conf.

Then, you can build the multimedia reference image:

$ bitbake tdx-reference-multimedia-image

Running Cog

In order to test cog, stop the main reference app:

# systemctl stop wayland-app-launch

In order to start Cog with the correct backend plugin, you need to execute:

# cog --platform=fdo

The following variables may be interesting for a better experience with the web browser:

# for full screen window, it worked but I could not see the mouse pointer
# and because there's no window decoration I could also not kill it anymore

# for setting the window size

Chromium Browser

Add Chromium using Yocto Project


To use chromium, you have to be aware of the specific requirements for the commercial license of libav and x264 packages.

As was done in the previous section, the first step is setting up Yocto build environment, as described in Build a Reference Image with Yocto Project/OpenEmbedded.

Then, to add Chromium to the build, clone the meta-browser repository.

$ cd ${LAYERDIR}

$ git clone -b master

As you are able to verify, the meta-browser layer has two other layers inside: meta-chromium and meta-firefox. In this section, just meta-chromium layer is going to be used.

$ cd meta-browser
$ tree -L 2
├── meta-chromium
│   ├── conf
│   ├──
│   └── recipes-browser
└── meta-firefox
├── classes
├── conf
├── recipes-browser
├── recipes-devtools
└── scripts

Chromium packages use the Clang compiler. So, you need to have meta-clang layer cloned inside the meta-oppenembedded layers directory. To read more about Clang, refer to Why and How to Use Clang Compiler with Yocto Project. Make sure to clone the Dunfell branch of the meta-clang layer.

$ cd ${LAYERDIR}/meta-openembedded/

$ git clone -b dunfell-clang12

$ cd meta-clang/

$ tree -L 1
├── classes
├── conf
├── _config.yml
├── dynamic-layers
├── recipes-bsp
├── recipes-connectivity
├── recipes-core
├── recipes-devtools
├── recipes-extended
├── recipes-graphics
├── recipes-kernel
└── recipes-multimedia

The next step is to add the chromium and clang layers to bblayers.conf

$ cd ${BUILD_DIR}

$ echo 'BBLAYERS += " ${TOPDIR}/../layers/meta-browser/meta-chromium"' >> conf/bblayers.conf

$ echo 'BBLAYERS += " ${TOPDIR}/../layers/meta-openembedded/meta-clang"' >> conf/bblayers.conf

Then, go to conf/local.conf and proceed with the following modifications:

IMAGE_INSTALL_append = " chromium-<suffix>"
LICENSE_FLAGS_WHITELIST += "commercial_libav commercial_x264"

Since Yocto Thud, chromium is available for both x11 and wayland backend. So, the suffix may be x-11 or ozone-wayland.

# Backend Selection
# Select the backend option (x11 or ozone-wayland) from the lines below:
# IMAGE_INSTALL_append = " chromium-x11"
IMAGE_INSTALL_append = " chromium-ozone-wayland"

Any more modifications that might have to be done, you can find at Why and How to Use Clang Compiler with Yocto Project.

The last step is to run the bitbake command.

$ bitbake tdx-reference-multimedia-image

Running Chromium

In order to test Chromium, stop the main reference app:

# systemctl stop wayland-app-launch

To start Chromium with the correct backend plugin, you need to execute:

# chromium --no-sandbox --ozone-platform=wayland

The flags, keys and variables listed at Chromium Command Line Switches should help to provide a better use of Chromium web browser.

GPU Accelerated Chromium

Hardware acceleration increases performance of the web browser, allowing the browser to move graphics and text rendering from the CPU to the GPU. To enable GPU acceleration on chromium you must use the switch --in-process-gpu, like the following example:

# chrome --no-sandbox --in-process-gpu

To check the Graphics Feature Status, go to chrome://gpu on your browser. You should see a list simillar to the one in the following image.

chromium GPU-accelerated feature status


Be aware that the list you might see in your chromium may be slightly different, deppending on your SoM, BSP and browser versions.

Send Feedback!