Building webOS Open Source Edition

This page describes how to build a webOS Open Source Edition (OSE) image from source code.

Before You Begin

• Make sure that your system meets the Build System Requirements.
• Basic knowledge about how to use Git is required.

Quick Summary

Here is a quick summary for users already familiar with building webOS OSE. If you are new to webOS OSE, we recommend reading the whole document thoroughly.

# Download source codes
$ git clone https://github.com/webosose/build-webos.git
$ cd build-webos

# Install and configure the build
$ sudo scripts/prerequisites.sh
$ ./mcf -p <half the num of CPUs> -b <half the num of CPUs> <image type>

# Start to build
$ source oe-init-build-env
$ bitbake webos-image

Cloning the Repository

You can start the webOS OSE build by cloning the build-webos repository.

$ git clone https://github.com/webosose/build-webos.git
$ cd build-webos

(Optional) How to Handle Patch Versions

Since webOS OSE consists of many open-source projects, changes in those projects can sometimes cause unexpected build-time errors. To address this issue, we introduced a new branch policy starting with the webOS OSE 2.19.1 release. This new policy enables the platform to quickly adapt to critical changes.

All you need to do is to check the patch number of the latest version.

• If the patch number is not zero, switch to the designated branch before starting the build.
• Otherwise, use the master branch.

# If the patch number of the latest version is not 0, checkout to the latest branch
# else, use the master branch
# Example) If the latest version is 2.19.1 (non-zero patch number)
$ git checkout 2.19.1

Installing the Required Tools and Libraries

During the building process, BitBake might fail a sanity check. Although BitBake tells you what is missing, it doesn’t install the missing tools and libraries.

You can force to install all of the missing software by entering the following:

$ sudo scripts/prerequisites.sh

Configuring the Build

Using the mcf command, you can set up the followings:

• The Type of webOS OSE image to build
• The number of logical CPU cores to allocate to the build process

$ ./mcf -p <num of CPUs> -b <num of CPUs> <image type>

Building the Image

webOS OSE provides two types of images:

• webos-image: A standard webOS OSE image
• webos-image-devel: A webOS OSE image with various development tools such as GDB and strace (system call tracer)

Building webos-image

To kick off a full build of webOS OSE, enter the following:

$ source oe-init-build-env
$ bitbake webos-image

Alternatively, you can enter:

$ make webos-image

Building webos-image-devel

$ source oe-init-build-env
$ bitbake webos-image-devel

Checking the Built Image

To check if the image has been built successfully, check the following directories:

• For Raspberry Pi 4, the resulting image will be created at
  • 32-bit: BUILD/deploy/images/raspberrypi4/webos-image-raspberrypi4.rootfs.wic.bz2.
  • 64-bit: BUILD/deploy/images/raspberrypi4-64/webos-image-raspberrypi4-64.rootfs.wic.bz2.
• For Raspberry Pi 3, the resulting image will be created at
  • 32-bit: BUILD/deploy/images/raspberrypi3/webos-image-raspberrypi3.rootfs.rpi-sdimg.
  • 64-bit: BUILD/deploy/images/raspberrypi3-64/webos-image-raspberrypi3-64.rootfs.rpi-sdimg.
• For the emulator, the resulting image will be created at
  • 32-bit: BUILD/deploy/images/qemux86/webos-image-qemux86-master-*-wic.vmdk.gz.
  • 64-bit: BUILD/deploy/images/qemux86-64/webos-image-qemux86-64-master-*-wic.vmdk.gz.

If the built image exists, move on to the Next Steps.

Cleaning

To blow away the build artifacts and prepare to do the clean build, you can remove the build directory and recreate it by typing:

$ rm -rf BUILD
$ ./mcf.status

This retains the caches of the downloaded source (under build-webos/downloads) and shared state (under build-webos/sstate-cache). These caches will save you a tremendous amount of time during development as they facilitate incremental builds, but these also can cause seemingly inexplicable behavior when corrupted.

For more details, see Yocto Project Overview and Concepts Manual.

Building and Cleaning Individual Components

To build an individual component, enter:

$ source oe-init-build-env
$ bitbake <component-name>

Alternatively, you can enter:

$ make <component-name>

To clean a component’s build artifacts under BUILD, enter:

$ source oe-init-build-env
$ bitbake -c clean <component-name>

To remove the shared state for a component as well as its build artifacts to ensure it gets rebuilt afresh from its source, enter:

$ source oe-init-build-env
$ bitbake -c cleansstate <component-name>

Troubleshooting Guide

Fetching Error During Build Process

webOS OSE fetches (downloads) many external modules during the build process. And these fetch jobs might fail occasionally.

In such case, try cloning the failed module manually. If the cloning succeeds, rerun the bitbake command to continue the build.

# Try cloning the failed module
$ git clone <fetch error module>
# If the cloning succeeds, rerun the build process
$ bitbake webos-image

Building Multiple Images On The Same Shell

If you try to build two (or more) different webOS OSE images on the same shell, this might cause a build error. To avoid such an error, do one of the following:

• Open a new shell and proceed from the Building webos-image.

• Enter the following commands and proceed from the Building webos-image.

  $ unset DISTRO
  $ unset MACHINE
  $ unset MACHINES
  

Next Steps

• If you built the image for Raspberry Pi 4 or Raspberry Pi 3, it’s time to flash the image to the target device. See Flashing webOS OSE.
• If you built the image for the emulator, refer to the Emulator User Guide to set up and use the emulator.

Appendix A. Setting Values for mcf

-p and -b options in mcf script are BitBake parallelism values, and those determine how many CPU cores are allocated for the building process.

Too many allocation for the parallelism values might cause build-time error. The recommended value is 50 to 70% of the toal logical CPU cores. To get the number of your computer, enter the following command:

# Get the number of logical CPU cores
$ cat /proc/cpuinfo | grep '^processor' | wc -l

Appendix B. Build Time Test

This section describes the actual build time of webOS OSE using our build machine.

Specifications of the test machine are as follows:

• CPU: Intel Xeon 6226R 2.9 GHz 2933 MHz 16C 150W
• RAM: 32 GB (16 GB x 2) DDR4 2933 DIMM ECC Registered 1CPI
• GPU: NVIDIA RTX A4000 16 GB FH Blower Fan 4DP PCle x16
• Storage: HP Z Turbo Drive M.2 2 TB TLC
• <num of CPUs> for mcf : 4

Test Results are as follows: