Building webOS Open Source Edition

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

Before You Begin

Note
If you cannot afford to build the image on your own, try with pre-built images.

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
$ git checkout <branch of the latest commit>

# Install and configure the build
$ sudo scripts/prerequisites.sh
$ ./mcf -p <num of CPUs> -b <num of CPUs> <device 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

Since webOS OSE 2.19.1, we introduced a new branch policy. This new policy allows the platform to implement important changes quickly. All you need to do is to checkout to the branch of the latest commit.

For example, if the latest commit of build-webos repository is in the 2.20 branch, check out to the 2.20 branch:

$ git checkout 2.20

But if the latest commit is in the master branch, a branch of the latest version doesn’t exist, use the master branch.

$ git checkout master

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:

  • A type of the webOS OSE image
  • How many resources to allocate to the build process
$ ./mcf -p <num of CPUs> -b <num of CPUs> <device type>
PropertyDescription
<num of CPUs>This number determines how CPU cores to allocate for the building process. See Appendix. How to Find the Optimum Parallelism Values.
<device type>A type of the webOS OSE image. Available values are as follows:
  • raspberrypi4: 32-bit image for webOS OSE 2.0 or higher
  • raspberrypi4-64: 64-bit image for webOS OSE 2.0 or higher
  • raspberrypi3: 32-bit image for webOS OSE 1.x version
  • raspberrypi3-64: 64-bit image for webOS OSE 1.x version
  • qemux86: 32-bit image for webOS OSE emulator
  • qemux86-64: 64-bit image for webOS OSE emulator (For webOS OSE 2.14.0 or higher)
Caution
Previous versions of webOS OSE might occur errors during build time. We only guarantee the build of the latest version.

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

IMPORTANT NOTICE
This process takes a very long time, especially on laptop computers. Make sure you have enough time and system resources to build. Regarding the build time, refer to our test results.

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
Caution

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:

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>

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. How to Find the Optimum Parallelism Values

To set the make and BitBake parallelism values, use -p and -b options to the mcf script. The -p and -b options correspond to PARALLEL_MAKE and BB_NUMBER_THREADS variables described in Yocto Project Development Tasks Manual.

The recommended value for -p and -b options is a half of the number of physical CPU cores. To get the number of physical CPU cores on your build system, use the following commands.

  1. Get the number of physical CPUs.

    $ cat /proc/cpuinfo | grep "physical id" | sort | uniq | wc -l
    1
    
  2. Get the number of cores per physical CPU.

    $ cat /proc/cpuinfo | grep "cpu cores" | uniq
    cpu cores    : 4
    
  3. Multiply the above two values.

    1 * 4 = 4 (The number of physical CPU cores)

With the above example, the recommended value for -p and -b options becomes 4 / 2 = 2.

Note
We recommend you use the value under two-thirds of the number of CPU cores.
Caution
Omitting -p and -b options are equivalent to using -p 0 -b 0, which forces the build to use all CPU cores. This might cause unexpected behaviors or a build failure.

Appendix B. Build Time Test

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

Build Machine Specification

  • 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

Device TypeImage TypeTime
raspberrypi4-64webos-image8 hours 48 minutes
raspberrypi4-64webos-image-devel8 hours 51 minutes

Contents