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 the four official migration guides (4.1 Langdale, 4.2 Mickledore, 4.3 Nanbield, 5.0 Scarthgap) 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. If you need to create a new layer for your custom patches, see the layer creation guide.

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. If you're overriding existing classes via .bbappend files, double-check the inherit path as well.

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.

FAQ

Can I skip intermediate versions and go directly from Kirkstone to Scarthgap?

Yes. Direct LTS-to-LTS migration is the recommended approach. Langdale, Mickledore, and Nanbield are already end-of-life, so there's no benefit to stepping through them. Just apply all breaking changes from all four versions at once using this checklist.

How long does a typical Kirkstone to Scarthgap migration take?

It depends on the number of custom layers and third-party dependencies. A project with 2-3 custom layers and standard BSP support typically takes a few days to a week. Projects with many custom recipes, pre-built binaries, or 32-bit targets (time_t ABI changes) can take longer.

What happens if I keep using Kirkstone after April 2026?

No more security patches from the Yocto Project. CVE fixes won't be backported, and community meta-layers will stop maintaining Kirkstone branches. You'd be responsible for all security patches yourself.

Do I need to update my BSP layer separately?

Yes. Your BSP vendor (e.g., NXP, TI, Raspberry Pi Foundation) needs to provide a Scarthgap-compatible branch. Check the OpenEmbedded Layer Index or the vendor's repository. If no Scarthgap branch exists, contact the vendor or fork the BSP layer and port it yourself.

Will my existing sstate-cache work after migration?

No. The sstate-cache from Kirkstone is not compatible with Scarthgap. You'll need a full rebuild. The first build will take as long as a clean build, but subsequent builds will populate the new sstate-cache.

Is the 64-bit time_t change relevant if I only target 64-bit platforms?

No. The 64-bit time_t change only affects 32-bit targets (ARM32, MIPS32, etc.). On 64-bit platforms, time_t has always been 64-bit, so the Y2038 change has no impact.

Should I enable cve-check during migration or after?

During. Scarthgap has create-spdx enabled by default, and adding cve-check at migration time means you start with a clean vulnerability baseline. Waiting until after migration means you'll have to retroactively audit your build.

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.

Related articles:

• Getting Started with Yocto: Build Your First Linux Image
• Yocto Build Errors: Task-by-Task Debugging Guide
• Raspberry Pi 5 with Yocto Scarthgap: A Practical Guide
• Yocto SBOM and CVE Management: A Practical Guide for Scarthgap
• Yocto systemd Auto-Start: Setup Guide with 7 Pitfalls
• Yocto Layer Creation Guide
• Yocto OTA Update: Comparing SWUpdate, RAUC, and Mender