Build an Image¶

You do not have to build anything to install libretouch if a release image is available for your board. Build from source to change the system, to add a board, or when no release covers your device.

Recommended environment¶

TI tests its Processor SDK Linux build environment against Ubuntu 22.04 and publishes a matching container image:

ghcr.io/texasinstruments/ubuntu-distro:latest

For an interactive workstation, use this image through Distrobox with rootless Podman. For CI or scripted builds, use the image directly with Docker or Podman. The image keeps the host distribution independent of the Ubuntu 22.04 build tools.

The ordinary build does not need --privileged, /dev, or /media mounts. Those should only be added for explicit hardware-access or flashing tasks.

Checkout¶

The layers are Git submodules of the top-level repository, and the recorded revisions belong together — clone recursively rather than updating layers individually:

git clone --recursive https://github.com/libretouch/libretouch.git
cd libretouch

If you already have a non-recursive clone:

git submodule update --init --recursive

Build¶

Source the environment once in the shell where BitBake will run:

source setup-environment

Then select a machine and build an image:

MACHINE=libretouch-usb bitbake libretouch-image

Machines are named after the boot method, not the product. One machine builds for every supported board: the kernel ships every board's device tree, and the bootloader loads the one that matches the board it is running on.

Machine	Image	Purpose
`libretouch-usb`	`libretouch-image`	Boot from a USB flash drive — see Create a USB installation
`libretouch-net`	`libretouch-image`	USB-RNDIS network boot — see USB RNDIS network boot
`libretouch-nand`	`libretouch-image-nand`	Installation to internal flash — see Install to internal flash

If MACHINE is not set, setup-environment selects libretouch-usb.

The environment exports BBPATH to the repository's build/ directory, so BitBake and bitbake-layers can be run from any current directory after the setup script has been sourced.

Inspect the configuration¶

source setup-environment
bitbake-layers show-layers
bitbake -p libretouch-image
bitbake-getvar MACHINE

Output and caches¶

Images and boot files are written below:

build/deploy-ti/images/<machine>/

That is not the usual Yocto location: the TI BSP layer redirects DEPLOY_DIR_IMAGE for ti-soc machines, so images land beside build/ rather than inside build/tmp/deploy/. Everything else — the licence manifests and, for a release build, the archived sources — stays under build/tmp/deploy/.

Downloaded source archives and shared state are kept outside the build directory:

downloads/
sstate-cache/

Both locations are ignored by Git and can be shared by compatible checkouts. The build/tmp/ directory is disposable build output.

Building a release¶

A build you intend to hand to someone else should also produce the corresponding sources for the copyleft components it contains:

LIBRETOUCH_RELEASE=1 MACHINE=libretouch-usb bitbake libretouch-image

The as-built sources, including the project's patches, land in build/tmp/deploy/sources/, and the licence manifest in build/tmp/deploy/licenses/. Distribute those alongside the image.

Rebuilding and cleaning¶

Force a recipe to compile again:

bitbake -c compile -f <recipe>

Clean a recipe's work output:

bitbake -c clean <recipe>

Use cleanall cautiously because it also removes downloaded source archives for the recipe:

bitbake -c cleanall <recipe>

Resource requirements¶

Yocto builds use substantial disk space, memory, and network bandwidth. Keep the build and download directories on local storage rather than a slow or unsupported network filesystem. If the host becomes unstable, reduce BB_NUMBER_THREADS and PARALLEL_MAKE in build/conf/local.conf.