How to Use Web Browser (Linux)
info
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.
Introduction
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.
TorizonCore
If you are looking for information on how to use web browsers on TorizonCore, refer to Web Browser / Kiosk Mode with TorizonCore.
Requirements
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:
- Build a Reference Image with Yocto Project/OpenEmbedded
- Custom meta layers, recipes and images in Yocto Project (hello-world examples)
- Reference Images for Yocto Project Software Downloads
- BSP Layers and Reference Images for Yocto Project Software
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.
info
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 https://github.com/Igalia/meta-webkit.git
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 https://github.com/meta-qt5/meta-qt5.git
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"
info
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 www.toradex.com
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
export COG_PLATFORM_FDO_VIEW_FULLSCREEN=1
# for setting the window size
export COG_PLATFORM_FDO_VIEW_WIDTH=1920
export COG_PLATFORM_FDO_VIEW_HEIGHT=1080
Chromium Browser
Add Chromium using Yocto Project
caution
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 https://github.com/OSSystems/meta-browser.git
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
.
├── COPYING.MIT
├── meta-chromium
│ ├── conf
│ ├── README.md
│ └── recipes-browser
└── meta-firefox
├── classes
├── conf
├── README.md
├── 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 https://github.com/kraj/meta-clang.git
$ cd meta-clang/
$ tree -L 1
.
├── classes
├── CODE_OF_CONDUCT.md
├── conf
├── _config.yml
├── CONTRIBUTING.md
├── COPYING.MIT
├── dynamic-layers
├── README.md
├── 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 www.toradex.com
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.
danger
Be aware that the list you might see in your chromium may be slightly different, deppending on your SoM, BSP and browser versions.