Building webOS Open Source Edition

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

Before You Begin

Ensure that your system meets the Build System Requirements.

Cloning the Repository

To build a webOS OSE image, build-webos repository is used. This repository contains the top level code that aggregates the various OpenEmbedded layers into a whole from which webOS OSE images can be built.

Set up build-webos by cloning its Git repository, and cd into the cloned directory:

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

Installing the Required Tools and Libraries

Before you can build, some tools and libraries need to be installed. If you try to build without them, BitBake will fail a sanity check and tell you what's missing, but not really how to get the missing pieces. On Ubuntu, you can force all of the missing pieces to be installed by entering:

$ sudo scripts/prerequisites.sh

Note
For more details about BitBake, refer to the BitBake Manual.

Configuring the Build

At this step, you can configure the build for your target device using the mcf script.

Setting the 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 option is (number of physical CPU cores / 2). To get the number of physical CPU cores on your build system, use the following commands.

Get the number of physical CPUs.

$ cat /proc/cpuinfo | grep "physical id" | sort | uniq | wc -l
1

Get the number of cores per physical CPU.

$ cat /proc/cpuinfo | grep "cpu cores" | uniq
cpu cores    : 4

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 option becomes 4 / 2 = 2.

Note
You can increase the value slightly, but make sure that the value does not exceed 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 can cause an unexpected behavior or a build failure, so it is strongly discouraged.

Configuring the Build for the Target Device

To configure the build for the target device and to fetch the sources, type:

$ ./mcf -p <number of physical CPU cores / 2> -b <number of physical CPU cores / 2> <target-device-name>

Currently, the available <target-device-name> are as follows:

raspberrypi4 (for webOS OSE 2.0 or higher)
raspberrypi3 (for webOS OSE 1.x version)
qemux86 (for emulator)

Building the Image

The following images can be built:

webos-image: The production webOS OSE image without development tools.
webos-image-devel: The image with various development tools added to webos-image, including 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

This may take in the neighborhood of two hours on a multi-core workstation with a fast disk subsystem and lots of memory, or many more hours on a laptop with less memory and slower disks.

Note

If you've built for some target device and attempt to build for another target device in the same shell, a build error might occur. 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

Building webos-image-devel

To build a webOS OSE image that includes GDB and strace for debugging, enter the following:

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

Note

For details on setting up the environment to debug webOS OSE with GDB, see GDB Debugging Setup.
For more information on how to use strace, refer to the article on strace.

Checking the Created Image

To see if the image has been created successfully, check the following files:

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

Once you checked the image file, 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

What this retains are the caches of the downloaded source (under ./downloads) and shared state (under ./sstate-cache). These caches will save you a tremendous amount of time during development as they facilitate incremental builds, but can cause seemingly inexplicable behavior when corrupted. If you experience strangeness, use the command presented below to remove the shared state of suspicious components. In extreme cases, you may need to remove the entire shared state cache. See Yocto Project Overview and Concepts Manual for more information on it.

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.