Add a Package#

Overview#

This skill is the end-to-end path for new Dakota packages.
Use it after not-bluefin.md has reset the repo model.

When to Use#

Use when you need to:

• add a new package to the image
• add a new service or preset shipped by a package
• add a config-only/import element
• wire new software into deps.bst

When NOT to Use#

• Remove an existing package → remove-package.md
• Update an existing package version → update-refs.md
• Debug a failing build → debugging.md
• Need only BST syntax or element-kind reference → buildstream.md

Core Process#

1. Pick the right element kind.
2. Copy a similar element as the starting point. There is no scaffold generator.
3. Create the new element under elements/bluefin/.
4. Wire it into the correct stack (usually elements/bluefin/deps.bst).
5. Add a source alias if the download domain is new.
6. Validate the graph before building.
7. Build the element, then the full image if needed.

Quick Start#

cp elements/bluefin/glow.bst elements/bluefin/<name>.bst
# edit the new element
just bst show oci/bluefin.bst
just bst build bluefin/<name>.bst

Choose Element Kind#

Service Installation Rules#

Enable services with preset files, never systemctl enable.

install-commands:
  - |
    sed -e 's|/usr/sbin/tailscaled|/usr/bin/tailscaled|g' \
        -e '/^EnvironmentFile=/d' \
        upstream.service > upstream.service.patched
    install -Dm644 -t "%{install-root}%{indep-libdir}/systemd/system" upstream.service.patched
  - |
    install -Dm644 /dev/stdin "%{install-root}%{indep-libdir}/systemd/system-preset/80-name.preset" <<'PRESET'
    enable service-name.service
    PRESET

Common Mistakes#

Common Rationalizations#

Red Flags#

• New package file exists but deps.bst was not touched
• Unit files install into old FHS paths
• Source URLs use fake variable expansion
• The plan mentions Containerfile or RPM steps

Verification#

• New element exists under elements/bluefin/
• Correct stack file was updated
• New source alias was added if needed
• just bst show oci/bluefin.bst passes
• The element builds successfully
• Service/preset files follow merged-usr and preset rules

Lessons Learned#

strip-binaries: "" is required for all non-ELF staging directories (2026-06-07)#

BST's default behavior calls strip on every binary in the staging area. If an element installs any file that is not a valid ELF binary (fonts, config files, shell scripts, pre-built tarballs, .so stubs), the build fails at the strip step with an obscure error. Always set strip-binaries: "" in the element's variables: block for:

• Font elements (.ttf, .otf, .woff2)
• Config-only elements (kind: import)
• Pre-built binary elements where upstream provides already-stripped binaries
• Any element where file -b <binary> returns something other than ELF

variables:
  strip-binaries: ""

BST variables cannot be used in source URL fields (2026-06-07)#

Unlike install commands where %{version} expands correctly, BuildStream does NOT expand variables inside sources[].url: fields. Use include/aliases.yml to define a URL alias, then reference the alias.

lsp-plugins 1.1.x is self-contained; 1.2.x requires network module fetching (2026-06-21)#

The sadko4u/lsp-plugins GitHub repo (redirects to lsp-plugins/lsp-plugins) switched to a modular
build system in the 1.2.x series that runs make fetch to download ~12 submodules at build time.
The 1.1.x series (latest: 1.1.26) is monolithic and BST-safe. Use 1.1.x for BST packaging.

Build LV2 only (no UI, no JACK, no standalone):

variables:
  make-args: >-
    BUILD_MODULES=lv2
    LV2_UI=0
    BUILD_R3D_BACKENDS=
    PREFIX=%{prefix}

External dep: freedesktop-sdk.bst:components/sndfile.bst. No external LV2 headers needed — bundled.