Classcraft / Yocto tools Source & docs

SCARTHGAP EDITION · YOCTO 5.0.13

Reusable classes.
Without the guesswork.

Turn a recipe pattern into a .bbclass. Start with a guided template, understand each decision, then take the metadata into your own layer.

01

Choose a starting point

Small, focused patterns you can build on.

Recipe classes are explicitly inherited by recipes. Global classes are loaded through configuration and must not assume a recipe task context.

Each template adds a namespaced task, never a blanket do_install append. Switching resets task ordering, runtime dependencies and the custom task editor. Installation templates turn exports off; variants turn off outside report/preflight. Anonymous code is preserved.

Lowercase letters, digits and underscores; start with a letter. Used to namespace tasks and variables.

Scoped directories are searched before shared classes, using BBPATH layer order. Shared classes may be loaded in either context.

02

Shape the task

Keep the contract small and predictable.

Shell uses POSIX sh and bbnote/bbfatal. Python uses BitBake's d datastore and bb.note/bb.fatal. Installation templates use shell staging into ${D}, never the host root. Changing language in the custom template resets its body to a matching starter.

03Advanced controls Optional · explained before you use them

Variable declarations

Added to the class after template defaults. = assigns with deferred expansion; ?= sets only if undefined at parse time (first wins); ??= is a weak fallback (last weak default wins); := expands now and preserves undefined references. Ordering matters. Both quote styles still expand BitBake references.

Values allow plain text, one style of quote, and ${VARIABLE} references. Backslashes, line breaks, inline Python and mixed quotes are rejected, not silently rewritten. This is a constrained metadata editor, not a security sandbox.

Choose set for assignments/defaults, or append/prepend/remove for expansion-time override operations. Append/prepend do not add spaces: put a leading/trailing separator in the value. BitBake applies append, then prepend, then remove. Conditions remain separate from operations.

Override tokens use modern colon syntax, e.g. class-native or qemux86-64. They take effect only when active in OVERRIDES. append/prepend/remove are operations, not accepted here as condition tokens. Expansion and override precedence are resolved by BitBake, not this preview.

Task hooks & exported implementations

Generate namespaced shell/Python helpers and attach them to this task's prefuncs/postfuncs varflags with +=. They log before/after this task inside its execution context, not as separately scheduled tasks. Existing hook lists are preserved; errors propagate.

EXPORT_FUNCTIONS keeps the original implementation at classname_functionname. The sample recipe replaces the namespaced public task and calls the original (shell function call or Python bb.build.exec_func). Flags stay on the public task. Limited to report/preflight/custom; installation templates keep their fixed fakeroot contract.

Anonymous Python · parse-time operations

Runs at recipe parse finalization, including bitbake -p/-e, not at task time. Guided options use only d.getVar/d.setVar/bb.fatal. A default applies only if undefined; a required value fails for missing/empty metadata and is supplied by the sample recipe. Custom code can have arbitrary side effects when you later run BitBake; it is not parsed or executed here.

Recipe variants

native builds for the build host; nativesdk for the SDK host, not the target. Only the no-source report/preflight examples support these switches; they omit allarch. The reusable class does not force variants on its inheritors. Real native/nativesdk path/dependency rewriting still needs OE-Core build validation. Target installation and custom-code templates cannot select variants here.

Inheritance & dependencies

Space-separated class names in declared order, inserted at the beginning. Earlier inheritance and later assignments can change results; inspect bitbake -e. These classes must exist on BBPATH. Do not inherit this class itself.

Space-separated recipe/provider names. Adds build dependencies for recipe sysroot integration, not runtime package installation. A tool generally needs its -native provider for host execution.

Space-separated package names, not recipe names. Available for data/configuration/service packages. Service output also adds coreutils for its true executable. Required packages must have real providers; no version expressions in this field.

Ordering & task flags

These apply only to the generated task. after makes it depend on predecessors; before makes successors depend on it. An after edge alone does not schedule this task into a normal build. Keep a reachable before edge. Cycles involving other metadata require BitBake to detect.

Space-separated full task names, e.g. do_patch. The asset task stays after do_install and before do_package and do_populate_sysroot so staging consumers see its output.

Existing content is preserved. The last directory becomes the task working directory. Restricted to ${WORKDIR} or ${B}, optionally followed by simple relative segments. No traversal or host paths.

Space-separated recipe:do_task pairs, e.g. zlib-native:do_populate_sysroot. Makes this task wait for those provider tasks. Unlike DEPENDS, this is a direct task edge, not general sysroot metadata.

Space-separated package:do_task pairs resolved in the runtime provider namespace. Does not add RDEPENDS package installation metadata. Use only when a real runtime provider task is needed.

Space-separated variable identifiers. Adds dependencies static analysis may miss (for example dynamically constructed d.getVar keys). Not a substitute for declaring actual file/tool inputs.

nostamp prevents a task stamp. It and dependent tasks can run on every build, causing rebuild cascades. Leave off for normal reproducible tasks.

LIVE METADATA

Your class, ready to review.

● Browser only

ZIP includes class, sample recipe, any source asset, layer.conf and a usage README. Downloads never run automatically. Requires an existing configured Scarthgap environment with the core layer.

THE FIELD GUIDE

Generate here. Verify in BitBake.

A structured preview is not a build result. Custom code is unparsed and untrusted; your sources, providers, overrides and toolchain must be checked in your real environment.

01 / Put it in a layer

Recipe: classes-recipe/name.bbclass with inherit name in a recipe. Global: classes-global/name.bbclass with INHERIT += "name" in configuration. Global generation is deliberately variables-only.

classes/ is the fallback shared directory for both contexts. Scoped directories are searched first across BBPATH; layer order can shadow same-named classes. Don't use a global class for per-recipe install tasks.

02 / Inspect before building

bitbake-layers show-layers
bitbake-layers show-recipes
bitbake -p
bitbake -e your-sample
bitbake -c listtasks your-sample
bitbake -g your-sample
bitbake your-sample

Run from an initialized Yocto build shell, after adding the layer. Replace your-sample with the generated recipe name. -p parses metadata; -e expands it (including trusted anonymous Python); -g writes dependency graphs, not a build. Inspect ${T}/log.do_* and run.do_* after tasks. The ZIP guide has exact commands.

03 / Advanced, intentionally explicit

Advanced controls now generate prefuncs/postfuncs logging helpers, EXPORT_FUNCTIONS implementations with recipe replacement examples, and guided or custom anonymous Python. Anonymous python () runs at parse finalization, even with -p/-e; keep it deterministic and trust all code.

BBCLASSEXTEND is generated on report/preflight sample recipes only; they omit allarch for native/SDK variants. Variable rows support conditional append/prepend/remove. Configuration and systemd templates supply their actual files, install tasks and package-scoped metadata. Native variants and target install templates cannot be mixed.

04 / Respect the build contract

Use ${D} for staged installation and the provided ${CC}/${CFLAGS}/${LDFLAGS} for cross-compilation. Never use host gcc or disable QA to hide errors. The data template uses install, not a compiler.

Signatures track task bodies and detected variable dependencies; stamps can skip unchanged work. vardeps fills analysis gaps. We deliberately omit cleandirs: it deletes and recreates directories before execution. No template performs host cleanup.

Release contract

Yocto 5.0.13 Scarthgap · bundled BitBake 2.8.1. Poky commit f16cffd030d21d12dd57bb95cfc310bda41f8a1f. Annotated tag object 529843b1c189ab7b133b7fdf197d4b2a4b71a6db points to that commit; it is not a commit SHA.

Yocto 5.0.13 structureBitBake 2.8 metadata manualPinned class lookup implementationDebugging & validation