Silicon Blade

Lesson

Working with WKS Files in Yocto

How Wic uses .wks files to create deployable disk images

Practical Yocto Project DevelopmentPlatform DevelopmentLesson 16 of 26

Sooner or later an image has to become something you can put on real storage. A root filesystem tarball is useful, but a board often needs a complete block image with a partition table, a boot partition, a root filesystem partition, and the right boot files in the right place.

That is what Wic is for. A .wks file describes the disk layout Wic should build from the artifacts Yocto has already produced.

What a .wks File Does

A .wks file is not the image itself. It is the layout recipe used by Wic while creating a .wic image.

image recipe
  -> root filesystem and boot artifacts
  -> Wic reads WKS_FILE
  -> .wic disk image under tmp/deploy/images/<machine>/

The .wks file answers questions such as:

  • which partitions should exist?
  • which partition gets the root filesystem?
  • which partition carries boot files?
  • which partition table format should be used?
  • what labels, sizes, alignment, and bootloader options are needed?

The details are board-specific, so I normally keep the Wic file close to the BSP or image metadata that owns that storage layout.

Where WKS Files Live in Wrynose

In Wrynose, WKS files should live under files/wic inside the layer that contains them.

For example, in a BSP layer:

Older Yocto material may show wic/ at the top of the layer. Do not copy that layout for Wrynose. Current metadata expects the WKS file under files/wic.

A Small Board Image Example

Suppose myboard boots from an SD card with:

  • a small FAT boot partition
  • an ext4 root filesystem partition
  • a GPT partition table

Create meta-my-bsp/files/wic/myboard.wks:

part /boot --source bootimg-partition --ondisk mmcblk0 --fstype=vfat --label boot --active --align 4096 --size 128
part / --source rootfs --ondisk mmcblk0 --fstype=ext4 --label rootfs --align 4096

bootloader --ptable gpt --append="rootwait"

Commands

The two important commands in this file are part and bootloader.

part

Creates a partition. The --source option tells Wic what should populate it.

bootloader

Describes bootloader-related image settings, such as the partition table type and kernel command-line additions.

Options

--source

What to place in the partition, for example bootimg, rootfs, or a filesystem image.

--ondisk

Which target device the partition belongs to, such as mmcblk0 or sda.

--fstype

The filesystem type, such as ext4, fat32, or ubifs.

--label

The filesystem label written into the partition.

--size

A size hint for the partition in MiB.

--source rootfs means Wic should populate that partition from the root filesystem produced by the image build. --source bootimg-partition uses the standard boot partition source plugin. The exact boot source you need depends on the machine and boot flow, so treat this as a practical starter example rather than a universal SD-card layout.

Selecting the WKS File

The build uses the WKS file when the image asks for a Wic output format and selects the layout.

For a board-specific layout, this often belongs in machine metadata:

IMAGE_FSTYPES += "wic.xz"
WKS_FILE = "myboard.wks"

That tells Yocto two things:

  • build a compressed Wic disk image
  • use myboard.wks as the Wic layout

You may see WKS_FILE in an image recipe instead when the layout is genuinely image-specific. If the partition layout is dictated by the board boot chain, I normally keep it with the machine or BSP metadata.

Build and Inspect the Result

Build the image as usual:

bitbake my-image

The resulting artifacts should appear under:

tmp/deploy/images/myboard/

For this example, expect files with names along these lines:

my-image-myboard.wic.xz
my-image-myboard.wic.bmap

The exact names depend on the image, machine, and enabled image types.

If you need to check the generated partition layout, decompress a copy and inspect it with normal disk-image tools:

xz -dk tmp/deploy/images/myboard/my-image-myboard.wic.xz
fdisk -l tmp/deploy/images/myboard/my-image-myboard.wic

For more detailed inspection, tools such as parted, wic ls, and wic cp can help you look inside the image without writing it to removable media first.

When the Image Does Not Boot

If the .wic image builds but the board does not boot, avoid treating the WKS file as the only suspect.

Check the chain:

  • did the build select the WKS file you expected?
  • did the deploy directory contain the kernel, device tree, bootloader, and image artifacts?
  • does the boot partition contain the files the bootloader expects?
  • does the kernel command line match the root filesystem partition?
  • does the filesystem type in the WKS file match what the kernel can mount early in boot?

This connects directly back to the kernel and boot lesson. Wic can assemble the disk image, but it cannot make a wrong device tree, wrong bootloader configuration, or wrong root filesystem argument correct by force of optimism.

Summary

Wic turns Yocto build artifacts into a deployable disk image.

The important points are:

  • Wrynose expects WKS files under files/wic in a layer
  • IMAGE_FSTYPES asks for a Wic image output
  • WKS_FILE selects the layout file
  • part defines partitions and their sources
  • bootloader controls partition-table and bootloader-related settings
  • the final .wic artifacts are written under tmp/deploy/images/<machine>/
  • inspect the generated image before assuming the failure is somewhere else

Check your understanding

Quick quiz: WKS files

Check how Wic and WKS files fit into deployable Yocto images.

Question 1What does a `.wks` file describe?
Question 2In Wrynose, where should project WKS files normally live inside a layer?
Question 3A `.wic` image builds but the board does not boot. What is the best next step?