Removing a Package

Overview

Systematic checklist for safely removing a package from the Bluefin image. The reverse of adding-a-package. Every step includes a verification command -- skip nothing.

When to Use

• Removing a bluefin/ or core/ element from the build
• Replacing a package with an alternative (remove old, then add new)
• Cleaning up abandoned packages

The Removal Checklist

Work through every step. Some steps will be no-ops -- the verification command tells you.

1. Identify all element files

# Find the element and any arch-specific variants
ls elements/bluefin/<name>*.bst elements/core/<name>*.bst 2>/dev/null

Multi-arch packages have a stack (e.g., tailscale.bst) plus per-arch elements (tailscale-x86_64.bst, tailscale-aarch64.bst). Remove all of them.

2. Check reverse dependencies

grep -r "<name>.bst" elements/

If other elements depend on this package, you must update or remove them too. Do not proceed until all reverse dependencies are resolved.

3. Remove from deps stack

Edit elements/bluefin/deps.bst -- remove the bluefin/<name>.bst line from depends:.

For core/ override elements, this step is different -- see Special Cases below.

4. Delete element files

rm elements/bluefin/<name>.bst        # main element
rm elements/bluefin/<name>-*.bst      # arch variants (if any)

5. Check source aliases

grep -rl "<alias_name>" elements/bluefin/ elements/core/ include/

Look at the element's url: fields to find which aliases it used. If an alias in include/aliases.yml is used only by the removed element, remove that alias.

6. Check tracking workflow

grep "<name>" .github/workflows/track-bst-sources.yml

Remove the element path from auto-merge or manual-merge groups. Also check the track-tarballs job for tarball-sourced elements.

7. Check Renovate config

grep -i "<name>" .github/renovate.json5

Remove any customManagers entries or packageRules that reference the element or its upstream dependency.

8. Clean up static files

grep -r "<name>" files/
ls files/<name>/ 2>/dev/null

Remove directories/files in files/ that were only used by this element (e.g., files/plymouth/ for the plymouth theme).

9. Clean up patches

ls patches/freedesktop-sdk/*<name>* patches/gnome-build-meta/*<name>* 2>/dev/null

Remove patches that only existed for this element. Check patch filenames and content.

10. Validate the build

just bst show oci/bluefin.bst    # dependency graph resolves
just build                        # full image builds

Special Cases

Core override elements (elements/core/)

Core elements are referenced from elements/gnome-build-meta.bst via config.overrides, not from deps.bst. To remove:

1. Delete the element file from elements/core/
2. Remove the corresponding overrides: entry in elements/gnome-build-meta.bst
3. The upstream gnome-build-meta element will be used instead

Multi-arch packages

A multi-arch package typically has 3 files: a stack element plus per-arch elements. The stack is listed in deps.bst; the arch elements are dependencies of the stack. Remove all files.

GNOME Shell extensions

Extensions live in elements/bluefin/shell-extensions/. Also remove from the elements/bluefin/gnome-shell-extensions.bst stack (not deps.bst).

Common Mistakes

Cross-References

• adding-a-package -- reverse workflow
• patching-upstream-junctions -- for junction patch cleanup
• buildstream-element-reference -- element kinds and structure