mirror of
https://github.com/outbackdingo/hyprcosmic.git
synced 2026-08-25 14:53:21 +00:00
Write the README for the fork, not for what it was forked from
The tree still carried cosmic-epoch's README, which describes how to install
COSMIC from a distribution's packages -- accurate, and about a different thing
than the repository it is now sitting in. Anyone arriving here needs to know
what changed, which two submodules are ours, how to build it, and what to do on
first login, and none of that was written down anywhere outside commit messages
and the comments in config/cosmic.conf.
Deliberately not a copy of upstream's. The dependency list, the packaging notes,
the per-distribution install instructions and the translation links are all
still correct and all still upstream's, so this links to them rather than
forking a second copy to go stale. What it says instead is the delta: the four
cosmic-comp patches, the session profile and what it stops starting, the
one-way config model, the theme import, the four per-user files `just install`
deliberately does not place, and what the two CI workflows each cover.
Two things in it are warnings rather than instructions, and are there because
leaving them out would make the document a nicer read and a worse one:
- prefix must be /usr in practice, and the reason is that some files name
/usr/share/hyprcosmic literally because they have no way to interpolate a
prefix. Written as its own paragraph rather than a footnote.
- `install` depends on `build`, so `sudo just install` compiles as root. That
is upstream's arrangement, inherited rather than chosen, and says so.
Every command, path and claim in it was checked against the tree: the CLI help,
the profile's disabled list, the socket names, the power menu's five entries,
the Shortcuts merge, and the theme path HyDE's own generated config records.
This commit is contained in:
@@ -1,346 +1,255 @@
|
|||||||
# COSMIC Desktop
|
# HyprCosmic
|
||||||
|
|
||||||
[COSMIC](https://system76.com/cosmic) is a desktop environment offering performance, efficiency, and personalization to empower a wide variety of use cases.
|
COSMIC's compositor, driven the way Hyprland is configured, wearing a HyDE
|
||||||
|
shell.
|
||||||
|
|
||||||
## Components of COSMIC Desktop
|
It is a fork of [cosmic-epoch](https://github.com/pop-os/cosmic-epoch), the
|
||||||
* [cosmic-applets](https://github.com/pop-os/cosmic-applets)
|
meta-repository that names every COSMIC component and builds the desktop out of
|
||||||
* [cosmic-applibrary](https://github.com/pop-os/cosmic-applibrary)
|
them. Two of its 29 submodules point at forks; the other 27 are System76's,
|
||||||
* [cosmic-bg](https://github.com/pop-os/cosmic-bg)
|
unchanged. So this is not a re-implementation of COSMIC and not a theme pack
|
||||||
* [cosmic-comp](https://github.com/pop-os/cosmic-comp)
|
sitting beside it — it is COSMIC, built from source, with a different shell on
|
||||||
* [cosmic-edit](https://github.com/pop-os/cosmic-edit)
|
top and a different way of telling it what to do.
|
||||||
* [cosmic-files](https://github.com/pop-os/cosmic-files)
|
|
||||||
* [cosmic-greeter](https://github.com/pop-os/cosmic-greeter)
|
|
||||||
* [cosmic-icons](https://github.com/pop-os/cosmic-icons)
|
|
||||||
* [cosmic-idle](https://github.com/pop-os/cosmic-idle)
|
|
||||||
* [cosmic-initial-setup](https://github.com/pop-os/cosmic-initial-setup)
|
|
||||||
* [cosmic-launcher](https://github.com/pop-os/cosmic-launcher)
|
|
||||||
* [cosmic-monitor](https://github.com/pop-os/cosmic-monitor)
|
|
||||||
* [cosmic-notifications](https://github.com/pop-os/cosmic-notifications)
|
|
||||||
* [cosmic-osd](https://github.com/pop-os/cosmic-osd)
|
|
||||||
* [cosmic-panel](https://github.com/pop-os/cosmic-panel)
|
|
||||||
* [cosmic-player](https://github.com/pop-os/cosmic-player)
|
|
||||||
* [cosmic-randr](https://github.com/pop-os/cosmic-randr)
|
|
||||||
* [cosmic-screenshot](https://github.com/pop-os/cosmic-screenshot)
|
|
||||||
* [cosmic-session](https://github.com/pop-os/cosmic-session)
|
|
||||||
* [cosmic-settings](https://github.com/pop-os/cosmic-settings)
|
|
||||||
* [cosmic-settings-daemon](https://github.com/pop-os/cosmic-settings-daemon)
|
|
||||||
* [cosmic-sound-theme](https://github.com/pop-os/cosmic-sound-theme)
|
|
||||||
* [cosmic-store](https://github.com/pop-os/cosmic-store)
|
|
||||||
* [cosmic-term](https://github.com/pop-os/cosmic-term)
|
|
||||||
* [cosmic-theme-editor](https://github.com/pop-os/cosmic-theme-editor)
|
|
||||||
* [cosmic-workspaces-epoch](https://github.com/pop-os/cosmic-workspaces-epoch)
|
|
||||||
* [xdg-desktop-portal-cosmic](https://github.com/pop-os/xdg-desktop-portal-cosmic)
|
|
||||||
* [pop-launcher](https://github.com/pop-os/launcher)
|
|
||||||
|
|
||||||
### COSMIC libraries/crates
|
Three things distinguish a HyprCosmic session from a COSMIC one:
|
||||||
|
|
||||||
* [cosmic-protocols](https://github.com/pop-os/cosmic-protocols)
|
- **Hyprland's configuration idiom.** A single `~/.config/hyprcosmic/cosmic.conf`
|
||||||
* [cosmic-text](https://github.com/pop-os/cosmic-text)
|
with `general { }` blocks, `bind =` lines and `$variables` is compiled into
|
||||||
* [cosmic-theme](https://github.com/pop-os/cosmic-theme)
|
COSMIC's config tree. The file wins: what it names, it owns.
|
||||||
* [cosmic-time](https://github.com/pop-os/cosmic-time)
|
- **HyDE's shell.** waybar instead of cosmic-panel, rofi instead of
|
||||||
|
cosmic-launcher, `awww` instead of cosmic-bg. HyDE themes are imported
|
||||||
|
directly, palette and wallpapers and all.
|
||||||
|
- **It installs beside COSMIC, not over it.** The two modified binaries go to
|
||||||
|
`/usr/libexec/hyprcosmic/`, and the session gets its own entry on the
|
||||||
|
greeter's menu. A machine with COSMIC from its distribution keeps that session
|
||||||
|
working, which matters on the day this one does not start.
|
||||||
|
|
||||||
### COSMIC toolkit for apps and applets
|
## Repository layout
|
||||||
|
|
||||||
* [libcosmic](https://github.com/pop-os/libcosmic)
|
Everything in `cosmic-epoch`, plus:
|
||||||
|
|
||||||
## Installing on Pop!\_OS
|
| Path | What it is |
|
||||||
|
| --- | --- |
|
||||||
|
| `cosmic-comp/` | submodule → [outbackdingo/hyprcosmic-comp](https://github.com/outbackdingo/hyprcosmic-comp) |
|
||||||
|
| `cosmic-session/` | submodule → [outbackdingo/hyprcosmic-session](https://github.com/outbackdingo/hyprcosmic-session) |
|
||||||
|
| `cosmic-conf/` | the config compiler and HyDE theme importer. A crate in this repository, not a submodule |
|
||||||
|
| `config/` | the shipped `cosmic.conf`, `autostart`, waybar and rofi assets, and the power menu |
|
||||||
|
| `tools/install-assets.sh` | installs the parts of `config/` that live outside `$HOME`, and `--check`s them for drift |
|
||||||
|
| `docs/` | the design spec, a debugging guide, and one written-up bug that is still open |
|
||||||
|
|
||||||
### Pop!\_OS 24.04
|
The other 27 submodules stay on `pop-os`. Nothing about them needs to change,
|
||||||
|
and pinning them to copies nobody maintains would be a promise to keep 27 forks
|
||||||
|
current.
|
||||||
|
|
||||||
COSMIC DE's first release (Epoch 1) is included in Pop!\_OS 24.04. There are two ways to get the 24.04 release:
|
### What the two forks change
|
||||||
|
|
||||||
- Install it from the [latest release ISO](https://system76.com/cosmic/).
|
**cosmic-comp** — four patches, each independent:
|
||||||
- Upgrade an existing Pop!\_OS 22.04 installation using the following command: `pop-upgrade release upgrade -f`
|
|
||||||
- If you experience problems during the upgrade, please open an issue in the [pop-upgrade GitHub repository](https://github.com/pop-os/upgrade) or join the [Pop!\_OS Mattermost chat server](https://chat.pop-os.org) for assistance.
|
|
||||||
|
|
||||||
COSMIC users, including Pop!_OS users, are welcome to join the [Pop!\_OS Mattermost chat server](https://chat.pop-os.org) to receive news about development. Join the [COSMIC Epoch channel](https://chat.pop-os.org/pop-os/channels/cosmic-epoch) for COSMIC user discussion, or the [Development channel](https://chat.pop-os.org/pop-os/channels/development) for developer-oriented discussion.
|
- `zwlr_foreign_toplevel_management_v1`, which is the protocol waybar's window
|
||||||
|
list and rofi's window mode read. Without it the taskbar is empty.
|
||||||
|
- A Hyprland-compatible IPC socket (`.socket.sock` and the `.socket2.sock` event
|
||||||
|
stream) under the names Hyprland clients actually open, so HyDE's scripts and
|
||||||
|
waybar's `hyprland/*` modules work unmodified. The write surface is
|
||||||
|
deliberately small: `dispatch exec` and `dispatch killactive` are rejected,
|
||||||
|
because this is the surface any process that can open the socket gets.
|
||||||
|
- New windows open *beside* the focused window rather than inside it.
|
||||||
|
- The install goes to `/usr/libexec/hyprcosmic/cosmic-comp`, and the shortcut
|
||||||
|
defaults file is left alone.
|
||||||
|
|
||||||
### Pop!\_OS 22.04
|
**cosmic-session** — profiles. `HYPRCOSMIC_PROFILE=hyprcosmic` (set by
|
||||||
|
`hyprcosmic.desktop`) skips cosmic-panel, cosmic-launcher, cosmic-app-library,
|
||||||
|
cosmic-workspaces, cosmic-bg and cosmic-files-applet, then starts whatever
|
||||||
|
`~/.config/hyprcosmic/autostart` names. cosmic-greeter is deliberately *not*
|
||||||
|
skippable — a display manager is the easiest thing to lock yourself out of. The
|
||||||
|
fork installs three files where upstream installs seven; the four it drops are
|
||||||
|
owned by the distribution's own `cosmic-session` package and writing them would
|
||||||
|
make the two conflict.
|
||||||
|
|
||||||
Due to dependency requirements, **COSMIC Epoch is no longer receiving updates on Pop!\_OS 22.04 LTS.** It's no longer recommended to test COSMIC Epoch on Pop!\_OS 22.04 because the latest bug fixes and features are only available on newer distributions such as Pop!\_OS 24.04.
|
## Building
|
||||||
|
|
||||||
Individual COSMIC applications work in the default GNOME session of Pop!\_OS 22.04. You can install individual COSMIC applications using the following command:
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo apt install cosmic-edit cosmic-files cosmic-player cosmic-store cosmic-term
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Old Release on 22.04
|
|
||||||
|
|
||||||
An **older release** of the COSMIC Epoch desktop environment alpha is still available on Pop!\_OS 22.04 LTS. If you encounter bugs while testing COSMIC Epoch on Pop!\_OS 22.04, please check if they exist in Pop!\_OS 24.04 before reporting them. You can install the older release on 22.04 with these instructions:
|
|
||||||
|
|
||||||
##### Enable Wayland
|
|
||||||
|
|
||||||
`sudo nano /etc/gdm3/custom.conf`
|
|
||||||
|
|
||||||
Change `WaylandEnable` to `true`:
|
|
||||||
```
|
|
||||||
WaylandEnable=true
|
|
||||||
```
|
|
||||||
|
|
||||||
Reboot for this change to take effect.
|
|
||||||
|
|
||||||
##### Update udev rules for NVIDIA users
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
sudo nano /usr/lib/udev/rules.d/61-gdm.rules
|
git clone --recurse-submodules https://github.com/outbackdingo/hyprcosmic
|
||||||
|
cd hyprcosmic
|
||||||
|
just build
|
||||||
```
|
```
|
||||||
|
|
||||||
Look for `LABEL="gdm_prefer_xorg"` and `LABEL="gdm_disable_wayland"`. Add `#` to the `RUN` statements so they look like this:
|
Build dependencies are COSMIC's — see [upstream's list](https://github.com/pop-os/cosmic-epoch#setup-on-distributions-without-packaging-of-cosmic-components),
|
||||||
|
which is long and distribution-specific. `rustup` is recommended over the
|
||||||
|
distribution's rustc: `cosmic-comp` is edition 2024 and pins Rust 1.93 in its
|
||||||
|
`rust-toolchain.toml`, which is newer than several stable distributions ship —
|
||||||
|
Debian bookworm's rustc is 1.63. `just` is likewise absent before Debian
|
||||||
|
trixie; `cargo install just --locked` covers it.
|
||||||
|
|
||||||
```
|
## Installing
|
||||||
LABEL="gdm_prefer_xorg"
|
|
||||||
#RUN+="/usr/libexec/gdm-runtime-config set daemon PreferredDisplayServer xorg"
|
|
||||||
GOTO="gdm_end"
|
|
||||||
|
|
||||||
LABEL="gdm_disable_wayland"
|
|
||||||
#RUN+="/usr/libexec/gdm-runtime-config set daemon WaylandEnable false"
|
|
||||||
GOTO="gdm_end"
|
|
||||||
```
|
|
||||||
|
|
||||||
Restart gdm
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
sudo systemctl restart gdm
|
sudo just install '' /usr
|
||||||
```
|
```
|
||||||
|
|
||||||
##### Install COSMIC
|
The two positional arguments are `rootdir` (a staging root, for packaging) and
|
||||||
|
`prefix`. **Use `/usr`, not the `/usr/local` default.** Several files name
|
||||||
|
`/usr/share/hyprcosmic` as a literal because they have no way to interpolate a
|
||||||
|
prefix — a rofi `.rasi` has no variables, `hyprcosmic.desktop` has no way to
|
||||||
|
expand one into `Exec=`, and `autostart` is deliberately not a shell.
|
||||||
|
`install-assets.sh` prints the exact list when you use another prefix.
|
||||||
|
|
||||||
`sudo apt install cosmic-session`
|
To stage instead of install:
|
||||||
|
|
||||||
After logging out, click on your user and there will be a sprocket at the bottom right. Change the setting to COSMIC. Proceed to log in.
|
|
||||||
|
|
||||||
## Installing on Arch Linux
|
|
||||||
Install via [cosmic-session](https://archlinux.org/packages/extra/x86_64/cosmic-session/) or the [cosmic](https://archlinux.org/groups/x86_64/cosmic/) group, e.g.:
|
|
||||||
`pacman -S cosmic-session` or `pacman -S cosmic`
|
|
||||||
|
|
||||||
Then log out, click on your user, and a sprocket at the bottom right shows an additional entry alongside your desktop environments. Change to COSMIC and proceed with log in.
|
|
||||||
For a more detailed discussion, consider the [relevant section in the Arch wiki](https://wiki.archlinux.org/title/COSMIC).
|
|
||||||
|
|
||||||
## Installing on Fedora Linux
|
|
||||||
|
|
||||||
COSMIC can be installed from the built-in repositories on Fedora 41+:
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo dnf install @cosmic-desktop-environment
|
|
||||||
```
|
|
||||||
|
|
||||||
Alternatively, for more up-to-date COSMIC packages (but less quality control), you can use the nightly COPR builds:
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo dnf copr enable ryanabx/cosmic-epoch && sudo dnf install cosmic-desktop
|
|
||||||
```
|
|
||||||
|
|
||||||
After installing, log out, click on your user, and use the sprocket in the bottom right to select the COSMIC desktop environment before logging in.
|
|
||||||
For more information, check the [Fedora Wiki COSMIC SIG page](https://fedoraproject.org/wiki/SIGs/COSMIC) or the [COPR page](https://copr.fedorainfracloud.org/coprs/ryanabx/cosmic-epoch/).
|
|
||||||
|
|
||||||
## Installing on NixOS
|
|
||||||
The COSMIC module on NixOS can be enabled by adding the following lines to
|
|
||||||
your NixOS configuration file (`configuration.nix` or in your Flake):
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
# Enable the COSMIC login manager
|
|
||||||
services.displayManager.cosmic-greeter.enable = true;
|
|
||||||
|
|
||||||
# Enable the COSMIC desktop environment
|
|
||||||
services.desktopManager.cosmic.enable = true;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
While some packages like `cosmic-session` might be present in prior versions,
|
|
||||||
the modules that add full support for COSMIC were added in **NixOS 25.05**.
|
|
||||||
|
|
||||||
You can find more details on the [NixOS Wiki](https://wiki.nixos.org/wiki/COSMIC).
|
|
||||||
|
|
||||||
|
|
||||||
## Installing on openSUSE tumbleweed
|
|
||||||
Cosmic can be installed by adding X11:COSMIC:Factory repo with opi.
|
|
||||||
```
|
|
||||||
opi patterns-cosmic
|
|
||||||
```
|
|
||||||
Select X11:COSMIC:Factory, after installing keep the repo.
|
|
||||||
|
|
||||||
Then log out, click on your user, and a sprocket at the bottom right shows an additional entry alongside your desktop environments. Change to COSMIC and proceed with log in.
|
|
||||||
For further information, you may check the [OBS page](https://build.opensuse.org/project/show/X11:COSMIC:Factory).
|
|
||||||
|
|
||||||
## Installing on Gentoo Linux
|
|
||||||
COSMIC can be installed on Gentoo via a custom overlay. Add the overlay using your preferred overlay manager (such as eselect), and then install the desktop environment:
|
|
||||||
|
|
||||||
`eselect repository add cosmic-overlay git https://github.com/fsvm88/cosmic-overlay.git`
|
|
||||||
|
|
||||||
Next, synchronize the repository with
|
|
||||||
`emaint sync -r cosmic-overlay`
|
|
||||||
|
|
||||||
and install the COSMIC desktop environment and its associated themes:
|
|
||||||
|
|
||||||
`emerge cosmic-meta pop-theme-meta -av`
|
|
||||||
|
|
||||||
Please note that the ebuilds have testing keywords and need to unmasked on stable systems for successful installation.
|
|
||||||
|
|
||||||
Then log out, and switch the desktop environment to COSMIC, the procedure depends on your login manager.
|
|
||||||
For further information, you may check the [Gentoo Wiki](https://wiki.gentoo.org/wiki/COSMIC) or [Overlay Repository](https://github.com/fsvm88/cosmic-overlay).
|
|
||||||
|
|
||||||
## Setup on distributions without packaging of COSMIC components
|
|
||||||
|
|
||||||
The COSMIC desktop environment requires a few dependencies. The rustc and just packages of your distro may be too old, so we recommend installing rustc and cargo with rustup, and installing just with cargo.
|
|
||||||
(This list does not try to be exhaustive, but rather tries to provide a decent starting point. For detailed instructions, check out the individual projects):
|
|
||||||
|
|
||||||
- [just](https://github.com/casey/just)
|
|
||||||
- rustc
|
|
||||||
- cargo
|
|
||||||
- c compiler (cc)
|
|
||||||
- make
|
|
||||||
- git
|
|
||||||
- libwayland
|
|
||||||
- mesa (or third-party libEGL/libGL implementations, though interfacing with mesa's libglvnd is generally recommended).
|
|
||||||
- libseat
|
|
||||||
- libxkbcommon
|
|
||||||
- libinput
|
|
||||||
- udev
|
|
||||||
- dbus
|
|
||||||
- libdisplay-info-dev
|
|
||||||
- libgstreamer1.0-dev
|
|
||||||
- libgstreamer-plugins-base1.0-dev
|
|
||||||
|
|
||||||
optionally (though the build-system might currently require these libraries):
|
|
||||||
- libsystem
|
|
||||||
- libpulse
|
|
||||||
- libexpat1
|
|
||||||
- libfontconfig
|
|
||||||
- libfreetype
|
|
||||||
- lld
|
|
||||||
- libgbm-dev
|
|
||||||
- libclang-dev
|
|
||||||
- libpipewire-0.3-dev
|
|
||||||
|
|
||||||
Note: `libfontconfig`, `libfreetype`, and `lld` are packages specific to Linux distributions. You may need to find the equivalent version for your distribution if you are not using Pop!_OS.
|
|
||||||
|
|
||||||
The required ones can be installed with:
|
|
||||||
```
|
|
||||||
sudo apt install -y \
|
|
||||||
build-essential \
|
|
||||||
dbus \
|
|
||||||
git \
|
|
||||||
libdbus-1-dev \
|
|
||||||
libdisplay-info-dev \
|
|
||||||
libflatpak-dev \
|
|
||||||
libglvnd-dev \
|
|
||||||
libgstreamer-plugins-base1.0-dev \
|
|
||||||
libgstreamer1.0-dev \
|
|
||||||
libinput-dev \
|
|
||||||
libpam0g-dev \
|
|
||||||
libpixman-1-dev \
|
|
||||||
libseat-dev \
|
|
||||||
libssl-dev \
|
|
||||||
libwayland-dev \
|
|
||||||
libxkbcommon-dev \
|
|
||||||
rustup \
|
|
||||||
udev
|
|
||||||
|
|
||||||
rustup toolchain install stable
|
|
||||||
cargo install just
|
|
||||||
```
|
|
||||||
|
|
||||||
and the optional ones with:
|
|
||||||
```
|
|
||||||
sudo apt install -y \
|
|
||||||
libclang-dev \
|
|
||||||
libexpat1-dev \
|
|
||||||
libfontconfig-dev \
|
|
||||||
libfreetype-dev \
|
|
||||||
libgbm-dev \
|
|
||||||
libpipewire-0.3-dev \
|
|
||||||
libpulse-dev \
|
|
||||||
libsystemd-dev \
|
|
||||||
lld \
|
|
||||||
mold
|
|
||||||
```
|
|
||||||
|
|
||||||
They can be installed all at once with:
|
|
||||||
```
|
|
||||||
sudo apt install -y \
|
|
||||||
build-essential \
|
|
||||||
dbus \
|
|
||||||
git \
|
|
||||||
libclang-dev \
|
|
||||||
libdbus-1-dev \
|
|
||||||
libdisplay-info-dev \
|
|
||||||
libexpat1-dev \
|
|
||||||
libflatpak-dev \
|
|
||||||
libfontconfig-dev \
|
|
||||||
libfreetype-dev \
|
|
||||||
libgbm-dev \
|
|
||||||
libglvnd-dev \
|
|
||||||
libgstreamer-plugins-base1.0-dev \
|
|
||||||
libgstreamer1.0-dev \
|
|
||||||
libinput-dev \
|
|
||||||
libpam0g-dev \
|
|
||||||
libpipewire-0.3-dev \
|
|
||||||
libpixman-1-dev \
|
|
||||||
libpulse-dev \
|
|
||||||
libseat-dev \
|
|
||||||
libssl-dev \
|
|
||||||
libsystemd-dev \
|
|
||||||
libwayland-dev \
|
|
||||||
libxkbcommon-dev \
|
|
||||||
lld \
|
|
||||||
mold \
|
|
||||||
rustup \
|
|
||||||
udev
|
|
||||||
|
|
||||||
rustup toolchain install stable
|
|
||||||
cargo install just
|
|
||||||
```
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
|
|
||||||
The easiest way to test COSMIC DE currently is by building a systemd system extension (see `man systemd-sysext`).
|
|
||||||
|
|
||||||
```
|
|
||||||
git clone --recurse-submodules https://github.com/pop-os/cosmic-epoch
|
|
||||||
cd cosmic-epoch
|
|
||||||
just sysext
|
|
||||||
```
|
|
||||||
|
|
||||||
This will create a system-extension called `cosmic-sysext`, which you can move (without renaming!) into e.g. `/var/lib/extensions`.
|
|
||||||
After starting systemd-sysext.service (`sudo systemctl enable --now systemd-sysext`) and refreshing (`sudo systemd-sysext refresh`) or rebooting,
|
|
||||||
COSMIC will be an available option in your favorite display manager.
|
|
||||||
|
|
||||||
If you have SELinux enabled (e.g. on Fedora), the installed extension won't have the correct labels applied.
|
|
||||||
To test COSMIC, you can temporarily disable it and restart `gdm` (note that this will close your running programs).
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
sudo setenforce 0
|
just install /tmp/stage /usr
|
||||||
sudo systemctl restart gdm
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Note**: An extension created this way will be linked against specific libraries on your system and will not work on other distributions.
|
This installs all of COSMIC — the 27 unmodified components as well — plus
|
||||||
It also requires the previously mentioned libraries/dependencies at runtime to be installed in your system (the system extension does not carry these libraries).
|
`cosmic-conf` at `$prefix/bin/cosmic-conf`, the shared waybar and rofi assets
|
||||||
|
under `$prefix/share/hyprcosmic/`, and `hyprcosmic-powermenu`.
|
||||||
|
|
||||||
**Read-Only Filesystem**: If you're not on an immutable distro you may notice that `/usr/` and `/opt/` are read-only.
|
`install` depends on `build`, which is upstream's arrangement and means `sudo
|
||||||
this is caused by `systemd-sysext` being enabled, when you are done testing you can disable `systemd-sysext` (`sudo systemctl disable --now systemd-sysext`)
|
just install` compiles as root. That is inherited, not chosen; if you would
|
||||||
|
rather not, build into a staging root as your own user and copy it into place.
|
||||||
|
|
||||||
It is thus not a proper method for long term deployment.
|
Then log out. `HyprCosmic` appears on the greeter's session menu next to
|
||||||
|
`COSMIC`; both work.
|
||||||
|
|
||||||
### Packaging
|
### Per-user setup
|
||||||
|
|
||||||
COSMIC DE is packaged for Pop!_OS. For reference, look at the `debian` folders in the projects repositories.
|
`just install` places nothing in a home directory — under `sudo` the only home
|
||||||
These and the `justfile` inside this repository may be used as references on how to package COSMIC DE, though no backwards-compatibility guarantees are provided at this stage.
|
directory it could see is root's. Four files are yours to place:
|
||||||
|
|
||||||
### Versioning
|
```shell
|
||||||
|
mkdir -p ~/.config/hyprcosmic/waybar
|
||||||
|
cp config/cosmic.conf config/autostart ~/.config/hyprcosmic/
|
||||||
|
cp config/waybar/style.css ~/.config/hyprcosmic/waybar/
|
||||||
|
```
|
||||||
|
|
||||||
COSMIC DE is a work in progress with many moving pieces.
|
`style.css` is per-user rather than shared for one reason: it `@import`s a
|
||||||
We do our best to keep the referenced submodule commits in this repository building and working together; as a consequence, they might not contain the latest updates and features from these repositories (yet).
|
sibling `theme.css` holding the installed HyDE theme's palette, and a relative
|
||||||
|
`@import` resolves against the importing file. That sibling is written by
|
||||||
|
`import-theme --assets`, so the bar is unstyled until you have imported a theme.
|
||||||
|
|
||||||
The commits corresponding with the current release are tagged `epoch-X.Y.Z`, where `X` is the major release and the last two numbers denote incremental minor releases. (During development of new major versions, an additional `-alpha.Y.Z` or `-beta.Y.Z` may be appended.)
|
The fourth file, `~/.config/rofi/config.rasi`, is written by `import-theme
|
||||||
|
--assets` too, because it names per-machine paths.
|
||||||
|
|
||||||
COSMIC Epoch version numbers are mainly for the benefit of non-Pop!_OS distributions; Pop!_OS uses its own build system, and typically receives updates to individual submodules before they're tagged as part of a COSMIC Epoch release.
|
Runtime dependencies of the shell itself are not COSMIC's and are not built
|
||||||
|
here: `waybar`, `rofi` (wayland build), `awww` (formerly `swww`), and a Nerd
|
||||||
|
Font for the bar's glyphs.
|
||||||
|
|
||||||
## Translating
|
## Configuration
|
||||||
|
|
||||||
To submit translations for COSMIC in your language, please use Weblate: https://hosted.weblate.org/projects/pop-os/
|
`~/.config/hyprcosmic/cosmic.conf`, in Hyprland's idiom, compiled into
|
||||||
|
`cosmic-config` by:
|
||||||
|
|
||||||
## Contact
|
```shell
|
||||||
- [Mattermost](https://chat.pop-os.org/)
|
cosmic-conf apply # once
|
||||||
- [Twitter](https://twitter.com/pop_os_official)
|
cosmic-conf apply --diff # show what would change, write nothing
|
||||||
- [Instagram](https://www.instagram.com/pop_os_official/)
|
cosmic-conf watch # recompile on every edit, for the whole session
|
||||||
|
```
|
||||||
|
|
||||||
|
`watch` is the first line of the shipped `autostart`, which is what makes "the
|
||||||
|
file wins" true at login and not only when you last ran `apply` by hand:
|
||||||
|
whatever COSMIC's settings UI stored since then is overwritten before the
|
||||||
|
desktop settles. A malformed edit is reported to the session log and the last
|
||||||
|
good configuration stays in place, so a typo cannot leave you at a broken
|
||||||
|
desktop.
|
||||||
|
|
||||||
|
The rule is one-way and deliberate. Keys this file names are overwritten from
|
||||||
|
it on every login; keys it does not name are left entirely alone, so
|
||||||
|
cosmic-settings remains the right place to change anything the file is silent
|
||||||
|
about. There is no write-back — the GUI never edits `cosmic.conf`.
|
||||||
|
|
||||||
|
`bind` lines go to the Shortcuts `custom` key, which cosmic-comp merges over
|
||||||
|
`defaults`, so the system defaults file is never touched and reverting is a
|
||||||
|
matter of deleting the lines and re-applying. Hyprland spellings and COSMIC
|
||||||
|
spellings are both accepted for the same setting (`input:follow_mouse` and
|
||||||
|
`general:focus_follows_cursor`), and the last assignment wins. Where a Hyprland
|
||||||
|
value has no COSMIC equivalent — `follow_mouse = 2` and `3`, which separate
|
||||||
|
pointer focus from keyboard focus — it is rejected with an explanation rather
|
||||||
|
than quietly rounded.
|
||||||
|
|
||||||
|
What the shipped file sets up, since the components those keys used to reach are
|
||||||
|
no longer running:
|
||||||
|
|
||||||
|
| Binding | Does |
|
||||||
|
| --- | --- |
|
||||||
|
| `Super` (tap), `Super+/`, `Super+A` | `rofi -show drun` |
|
||||||
|
| `Super+W` | `rofi -show window`, in place of the workspace overview |
|
||||||
|
| `Super+Return` | `cosmic-term` (`Super+T` still works — cosmic-comp handles that one itself) |
|
||||||
|
| `Super+Shift+E` | `hyprcosmic-powermenu`: lock, suspend, log out, reboot, shut down |
|
||||||
|
|
||||||
|
The power menu is there because cosmic-panel hosts COSMIC's power applet, and
|
||||||
|
without the panel a session had no way out short of `systemctl reboot` from a
|
||||||
|
terminal. The same script backs waybar's power button, so the two cannot drift
|
||||||
|
apart, and it confirms before anything that ends the session.
|
||||||
|
|
||||||
|
See [`config/cosmic.conf`](config/cosmic.conf); it is commented at length and is
|
||||||
|
the reference for what is supported.
|
||||||
|
|
||||||
|
## Theming
|
||||||
|
|
||||||
|
```shell
|
||||||
|
cosmic-conf import-theme ~/.config/hyde/themes/'Tokyo Night'/hypr.theme \
|
||||||
|
--out ~/.config/hyprcosmic/theme.conf --report --assets
|
||||||
|
```
|
||||||
|
|
||||||
|
This translates a HyDE theme into conf keys, and with `--assets` also installs
|
||||||
|
the wallpapers, GTK and icon themes, and the waybar/rofi/kitty theme files that
|
||||||
|
sit beside `hypr.theme`. `--report` prints everything that did not translate
|
||||||
|
cleanly, which is the honest half of the output.
|
||||||
|
|
||||||
|
`theme.conf` is written as a separate file and `source`d from `cosmic.conf`
|
||||||
|
rather than pasted into it. That keeps re-importing from touching your
|
||||||
|
keybindings, and anything you want to override can simply be repeated later in
|
||||||
|
`cosmic.conf`, since the last assignment to a key wins. The `source` line ships
|
||||||
|
commented out — a `source` naming a file that does not exist is a hard error,
|
||||||
|
and no theme is imported on a fresh install. Uncomment it once you have run the
|
||||||
|
command above; `import-theme` says so as well.
|
||||||
|
|
||||||
|
Change the wallpaper by repointing the `current` symlink that `--assets`
|
||||||
|
maintains, not by editing `autostart`:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
ln -sfn ~/".local/share/wallpapers/hyprcosmic/<theme>/<image>" \
|
||||||
|
~/.local/share/wallpapers/hyprcosmic/current
|
||||||
|
```
|
||||||
|
|
||||||
|
## Continuous integration
|
||||||
|
|
||||||
|
Two workflows, on purpose:
|
||||||
|
|
||||||
|
- `.github/workflows/ci.yml` is upstream's, unmodified. It builds the entire
|
||||||
|
desktop on Arch via `just sysext`, which is exactly the check a meta-repo
|
||||||
|
wants and is not made less useful by forking.
|
||||||
|
- `.github/workflows/hyprcosmic.yml` covers what upstream's does not:
|
||||||
|
`cosmic-conf` built, tested and clippy-clean on Fedora, Debian and Arch; a
|
||||||
|
check that the shipped `cosmic.conf` still parses and resolves against the
|
||||||
|
current schema; that `config/waybar/config.jsonc` is still in step with the
|
||||||
|
generator that produces it; that the template and generator stay pure ASCII;
|
||||||
|
and an `install-assets.sh` round trip into a staging root, verified with
|
||||||
|
`--check`.
|
||||||
|
|
||||||
|
The two forks carry a `hyprcosmic.yml` of the same shape, each asserting that
|
||||||
|
its install landed in `/usr/libexec/hyprcosmic/` and that the files owned by the
|
||||||
|
distribution's COSMIC packages went unwritten.
|
||||||
|
|
||||||
|
The waybar generator deserves its own note. `config.jsonc` is generated from
|
||||||
|
`config.jsonc.in` and a codepoint table in `generate-config.py`, and is never
|
||||||
|
hand-edited: Nerd Font glyphs live in the Private Use Area, where they are
|
||||||
|
destroyed by being retyped and indistinguishable from each other in a diff. CI
|
||||||
|
regenerates the file and fails if it moves.
|
||||||
|
|
||||||
|
## Known gaps
|
||||||
|
|
||||||
|
- The `/usr/share/hyprcosmic` literals described under [Installing](#installing).
|
||||||
|
- `docs/unreproducible-dead-input-2026-08-10.md` records a session that came up
|
||||||
|
without input and has not been reproduced since. It is written down rather
|
||||||
|
than closed.
|
||||||
|
|
||||||
|
## Trademark
|
||||||
|
|
||||||
|
COSMIC is a System76 trademark. This fork is not affiliated with or endorsed by
|
||||||
|
System76. See [TRADEMARK.md](TRADEMARK.md), which is upstream's policy and
|
||||||
|
applies here.
|
||||||
|
|
||||||
|
## Upstream
|
||||||
|
|
||||||
|
For COSMIC itself — the component list, packaging status, translations, and how
|
||||||
|
to install it on your distribution rather than building it — see
|
||||||
|
[pop-os/cosmic-epoch](https://github.com/pop-os/cosmic-epoch).
|
||||||
|
|||||||
Reference in New Issue
Block a user