| name | add-fsdk-component |
| version | 1.1 |
| last_updated | 2026-08-20T00:00:00.000Z |
| id | add-fsdk-component |
| one_line_purpose | Add an FSDK component and stack element without building an OCI image. |
| entry_point | docs/skills/add-fsdk-component/SKILL.md |
| category | ci-ops |
| mcp_compliance_level | partial |
| optimization_status | draft |
| status | active |
| dependencies | [] |
| tags | ["buildstream","fsdk","elements","components"] |
| description | Add a component + stack element (no OCI image) composed from FSDK, e.g. a tool consumed by a future VM/appliance image. Use when the deliverable is `elements/<name>/<name>.bst` + `<name>-stack.bst` only, not a full distroless image. |
| metadata | {"type":"procedure","context7-sources":["/apache/buildstream"]} |
Add an FSDK Component (no OCI image)
Use when a task asks for a buildable, checkout-able BuildStream component and
its stack, but explicitly not an OCI image (elements/oci/*.bst) — e.g. a
piece that a later VM/appliance task will consume. For the full three-element
OCI image pattern, see add-new-image.md instead.
Live examples: elements/qemu-img/ (meson), elements/lab-runner/*.bst
(tar/binary manual elements).
1. Research with Context7 first
Resolve the upstream project's current build-system and packaging docs
before picking versions or dependency elements — build systems change between
major versions. Don't stop at the dependency manifest: verify which imports
are hard vs. optional (try/except, lazy) by reading upstream source, scoped to
the feature path your task needs.
2. Element kind: manual only
This project's project.conf does not register the meson or
pyproject element kinds (those live inside freedesktop-sdk's own project).
Every hand-authored element here uses kind: manual with hand-written shell —
see elements/qemu-img/qemu-img.bst (invokes meson setup/ninja/meson install directly).
A bare kind: manual element with minimal build-depends has no shell in
its sandbox — mkdir, cat, etc. fail with "Staged artifacts do not provide
command 'sh'". Add a shell stack (e.g.
freedesktop-sdk.bst:public-stacks/runtime-minimal.bst; on FSDK 26.08 bash
moved, so check which stack provides it — elements/brew/brew-prefix.bst
stages runtime-gnu + runtime-minimal for this reason) to build-depends.
3. Dependency type is when, not just whether
The single easiest mistake; it fails silently with a confusing downstream
error (e.g. ModuleNotFoundError deep inside a build-time script):
build-depends — staged only while building this element.runtime-depends — not staged during this element's own build, only
visible to elements that depend on this one. A tool your own build commands
invoke must NOT be listed here.
