Kirkstone to Scarthgap Migration: The Complete Checklist

Kirkstone 4.0 LTS support ends April 27, 2026. That's weeks away.

The next LTS, Scarthgap 5.0, is supported until April 2028. Migration is inevitable. But four releases sit between Kirkstone and Scarthgap, each with its own breaking changes.

This guide consolidates every breaking change from four official migration guides into one checklist, with real error examples and fixes.

Why Migrate to Scarthgap Now

Four releases separate Kirkstone from Scarthgap.

Langdale, Mickledore, and Nanbield are already end-of-life. Direct LTS-to-LTS migration (Kirkstone → Scarthgap) is the practical path.

Three reasons to migrate now.

1. Security patches stop

After EOL, CVE fixes won't be backported. Running an unpatched build system on embedded products is a security risk.

2. EU CRA compliance

The EU Cyber Resilience Act takes full effect in December 2027. Vulnerability management becomes mandatory, but an EOL build system can't maintain CVE scanning and SBOM generation with current data.

3. Ecosystem support

BSP vendors and community meta-layers shift focus to the current LTS. Kirkstone support will gradually decline.

Before You Start

Set up your environment before changing code.

Record your current layer configuration

bitbake-layers show-layers

Save this output. You'll use it to verify nothing was lost after migration.

Check Scarthgap support for each layer

Look up each layer in the OpenEmbedded Layer Index, or check the remote branches directly.

# Check if a layer has a scarthgap branch
cd meta-custom-bsp
git branch -r | grep scarthgap

Layers without a Scarthgap branch need to be forked and ported, or replaced with alternatives.

Update LAYERSERIES_COMPAT

Update conf/layer.conf in your custom layers.

# meta-mylayer/conf/layer.conf
LAYERSERIES_COMPAT_meta-mylayer = "scarthgap"

Without this, BitBake refuses to load the layer.

Git branch strategy

Create a migration branch to keep your Kirkstone build intact.

git checkout -b migration/scarthgap

Breaking Changes Checklist

Four versions of breaking changes, organized by impact. Check each item against your recipes and configuration.

Classes directory split (4.1 Langdale)

In Langdale, the classes/ directory was split into three.

What breaks: Using INHERIT += with a class that lives in classes-recipe/ causes a parse error.

# This fails (testimage is in classes-recipe/)
INHERIT += "testimage"

# Correct
IMAGE_CLASSES += "testimage"

Custom classes in classes/ continue to work. However, moving them to the appropriate directory is recommended for future compatibility.

SERIAL_CONSOLE removal (4.2 Mickledore)

SERIAL_CONSOLE (singular) was deprecated since version 2.6 (Thud, 2018) and fully removed in Mickledore.

# Kirkstone (works but deprecated)
SERIAL_CONSOLE = "115200 ttyS0"

# Scarthgap (required)
SERIAL_CONSOLES = "115200;ttyS0"

Two changes to note:

• Variable name is now plural (SERIAL_CONSOLES)
• Separator changed from space to semicolon

Search your machine configuration files with grep -r "SERIAL_CONSOLE " and update all occurrences.

64-bit time_t default (4.3 Nanbield)

On 32-bit platforms (e.g., ARM32), time_t is now 64-bit by default to address the Y2038 overflow problem.

What breaks:

• ABI compatibility breaks on 32-bit targets
• Pre-built binaries compiled with 32-bit time_t can't be linked
• OLDEST_KERNEL changed to "5.15" — kernels older than 5.15 are no longer supported

If you target 32-bit platforms, verify that any third-party binaries (pre-compiled libraries, etc.) are compatible with 64-bit time_t.

CVE_CHECK_IGNORE deprecation (5.0 Scarthgap)

The CVE exclusion mechanism changed.

# Kirkstone
CVE_CHECK_IGNORE += "CVE-2024-12345"

# Scarthgap (recommended)
CVE_STATUS[CVE-2024-12345] = "not-applicable-platform: Only affects Windows"

CVE_CHECK_IGNORE still works in Scarthgap but triggers deprecation warnings. The new CVE_STATUS records the exclusion reason, making it audit-friendly for SBOM/CVE management.

ipk compression change (5.0 Scarthgap)

ipk package compression switched from xz to zstd.

What breaks: ipk packages built with Scarthgap can't be installed on targets running older Opkg without zstd support.

This matters if you push OTA updates from Scarthgap builds to devices running older firmware. Either update Opkg on the target to a zstd-capable version, or configure the build to use xz compression.

Other variable removals and renames

Common Migration Errors and Fixes

Real errors you'll encounter during migration and how to resolve them.

Layer compatibility error

ERROR: Layer 'meta-custom' is not compatible with the current set of layers

LAYERSERIES_COMPAT doesn't include scarthgap. Fix conf/layer.conf.

# meta-custom/conf/layer.conf
LAYERSERIES_COMPAT_meta-custom = "scarthgap"

For more error debugging techniques, see the build error debugging guide.

Class not found

ERROR: ParseError: Could not inherit file classes/testimage.bbclass

The 4.1 classes directory split moved recipe-only classes out of the default search path for INHERIT +=. Switch to IMAGE_CLASSES or inherit as appropriate.

SERIAL_CONSOLE syntax error

ERROR: Variable SERIAL_CONSOLE is no longer supported

Replace with SERIAL_CONSOLES (plural) and change the separator to semicolons.

time_t build failures

On 32-bit targets, linking against third-party libraries may produce size mismatch errors.

error: size of 'timestamp' changed to 8 bytes (was 4)

Solutions:

1. Rebuild the library within the Scarthgap environment
2. As a last resort, set TIME_T_BITS = "32" at the recipe level (not recommended)

ipk installation failure

opkg install: Unknown compression type 'zstd'

This happens when deploying Scarthgap-built ipk packages to older devices. The recommended fix is updating Opkg on the target to a zstd-capable version.

Features Worth Using in Scarthgap

While you're migrating, take advantage of what Scarthgap offers.

SBOM generation enabled by default

Scarthgap includes create-spdx in Poky's default configuration. Every build automatically generates SPDX-format SBOMs.

EU CRA compliance for SBOM generation comes at zero additional effort. See the SBOM/CVE management guide for production workflows.

Pressure-based build control

# conf/local.conf
BB_PRESSURE_MAX_CPU = "150"
BB_PRESSURE_MAX_IO = "80"
BB_PRESSURE_MAX_MEMORY = "50"

Uses Linux's /proc/pressure/ to dynamically adjust BitBake task parallelism based on real-time CPU, I/O, and memory pressure. More flexible than fixed BB_NUMBER_THREADS values. See the build speed optimization guide for details.

CVE_STATUS_GROUPS

Group CVE exclusions by reason for easier management.

# conf/local.conf
CVE_STATUS_GROUPS = "CVE_STATUS_WIN"
CVE_STATUS_WIN = "CVE-2024-11111 CVE-2024-22222"
CVE_STATUS_WIN[status] = "not-applicable-platform: Windows-only"

Much cleaner than individual CVE_STATUS entries when you have dozens of exclusions.

Wrapping Up

Kirkstone to Scarthgap migration spans four versions of changes, but the high-impact items are manageable.

The migration workflow:

1. Verify Scarthgap branch availability for all layers
2. Update LAYERSERIES_COMPAT
3. Run through the checklist with grep -r
4. Build → fix errors → repeat
5. Enable cve-check and start vulnerability management

Kirkstone's end-of-life is imminent. Use this checklist to take the shortest path to Scarthgap.