Architecture

Architecture

Repository layout

cosmic-overlay/
├── cosmic-base/        # Primary category: COSMIC DE apps + Pop!_OS components
├── cosmic-extra/        # Community add-ons layered on top of COSMIC (e.g. cutecosmic)
├── cosmic-utils/        # Packages from the community github.com/cosmic-utils org
├── acct-group/          # System groups needed by daemons (e.g. cosmic-greeter)
├── acct-user/           # System users needed by daemons (e.g. cosmic-greeter)
├── virtual/              # Virtual packages
├── x11-themes/           # Theming packages (e.g. adw-gtk3)
├── dev-lang/, dev-util/  # Toolchain packages COSMIC/tooling needs (dart, buf, dart-sass...)
├── eclass/               # Shared build logic (see below)
├── scripts/              # Maintainer automation (see [[Bumping Ebuilds]], [[QA and Testing]])
├── profiles/             # Gentoo repo profile data
└── metadata/layout.conf  # masters = gentoo, thin-manifests = true

cosmic-base used to be cosmic-de; packages were migrated in 05.2025 via pkgmove. Users on the old category need to sync once to get the automatic move.

Eclasses

All COSMIC packages inherit shared logic from eclass/:

• cosmic-common.eclass — common helpers shared by both live and tagged ebuilds (install helpers like cosmic-common_install_metainfo, target dir handling, etc).
• cosmic-de-r2.eclass — the main eclass tagged/versioned COSMIC ebuilds inherit: Rust build profile handling (RUST_MIN_VER), USE flags, cargo invocation.
• cosmic-live.eclass — equivalent logic specialized for -9999 live ebuilds tracking upstream master.

Because nearly every package in cosmic-base inherits one of these, an eclass change has repo-wide blast radius — see the eclass note in Maintainer Guide.

USE flags (from the eclass)

• debug — cargo build --profile debug
• debug-line-tables-only — adds profile.$profile_name.debug="line-tables-only", useful for stack traces regardless of profile
• max-opt — injected release-maximum-optimization profile (1 codegen unit, opt-level=3); mutually exclusive with debug

Versioning model

• Tagged/stable ebuilds track upstream release tags from pop-os/cosmic-epoch, e.g. epoch-1.4.0. The overlay version drops the epoch- prefix (cosmic-comp-1.4.0.ebuild).
• Live ebuilds (-9999) track upstream master directly and are keyword-masked by default (masked via missing keywords, not ~arch).
• Revisions (-r1, -r2, ...) are reserved for overlay-side patch bumps (backports, ebuild fixes) — not for upstream source changes. PVR was deliberately dropped from SRC_URI for this reason (an upstream re-tag should mean a new PV, not a revision bump).

Vendoring model

Non-live ebuilds don't build against the live network — dependency crates are pre-vendored:

1. cargo vendor --locked is run against the upstream tag to produce a vendored dependency set.
2. That's compressed with zstd and uploaded as a GitHub release asset in this repo (not upstream), tagged to match the ebuild version.
3. The ebuild's Manifest records DIST entries with BLAKE2B/SHA512 hashes for both the upstream source tarball and the vendor tarball.

iced/libcosmic system libraries were tried at one point and dropped (see commit fec5043) — Rust's static linking model makes unbundling not worth the effort here.

CI

Two workflows in .github/workflows/:

• qa-check.yml — runs pkgcheck scan + pkgdev manifest inside a Gentoo Docker container, on push/PR to main and weekly (Sundays 06:00 UTC). Comments QA summaries on PRs, uploads HTML/Markdown/JSON reports as artifacts.
• deploy-pages.yml — publishes the QA reports from main to GitHub Pages at https://fsvm88.github.io/cosmic-overlay/qa-reports/.

pkgcheck config lives in scripts/pkgcheck.conf (amd64/arm64 only, RequiredUseDefaults/RedundantVersion warnings disabled as not relevant to an overlay).