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

Every COSMIC package ebuild inherits exactly one of two top-level eclasses, which both in turn inherit cosmic-common (plus cargo, xdg, llvm-r1):

• cosmic-de-r2.eclass — for tagged/versioned ebuilds. Rust build profile handling (RUST_MIN_VER), USE flags, cargo invocation.
• cosmic-live.eclass — the same, for -9999 live ebuilds tracking upstream master; additionally inherits git-r3.
• cosmic-common.eclass — shared helpers both of the above pull in (install helpers like cosmic-common_install_metainfo, target dir handling, etc). Not inherited directly by package ebuilds.

Because nearly every package in cosmic-base inherits one of these (directly inherit cosmic-de-r2 or inherit cosmic-live, both usually combined with desktop and sometimes systemd/pam/tmpfiles), 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).