From cf1180df7ba9c8f1180ab3a902746d4f169c556f Mon Sep 17 00:00:00 2001 From: 2 * r + 2 * t <61896496+soramanew@users.noreply.github.com> Date: Sat, 28 Jun 2025 00:30:50 +1000 Subject: readme: add stuff Fixes #171 Add installation, update usage --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 99 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 7c39cb8..e1dd87c 100644 --- a/README.md +++ b/README.md @@ -9,95 +9,141 @@ -> [!WARNING] -> The overhaul is finished! -> Installation is now via an [install script](https://github.com/caelestia-dots/caelestia/blob/main/install.fish) in the -> [`caelestia` repo](https://github.com/caelestia-dots/caelestia). -> -> Anyone with an existing installation, please reinstall via the install script. -> -> Some breaking changes: -> - Rename the `scripts` repo -> `cli` -> - Rename the `hypr` repo -> `caelestia` -> - Merge all other repos (except this and `cli`) into `caelestia` -> - Installation for the `shell` and `cli` will be done via AUR packages; `caelestia` will have a meta package and an install script (should fix most installation issues) -> - Overhaul the scheme system (should fix a few bugs with that and make it cleaner in general) - https://github.com/user-attachments/assets/0840f496-575c-4ca6-83a8-87bb01a85c5f ## Components -- Widgets: [`Quickshell`](https://quickshell.outfoxxed.me) -- Window manager: [`Hyprland`](https://hyprland.org) -- Dots: [`caelestia`](https://github.com/caelestia-dots) +- Widgets: [`Quickshell`](https://quickshell.outfoxxed.me) +- Window manager: [`Hyprland`](https://hyprland.org) +- Dots: [`caelestia`](https://github.com/caelestia-dots) ## Installation -This is not implemented as of now. - -## Usage - -The shell can be started in two ways: via systemd or manually running `caelestia shell`. - -### Via systemd +> [!NOTE] +> This repo is for the desktop shell of the caelestia dots. If you want installation instructions +> for the entire dots, head to [the main repo](https://github.com/caelestia-dots/caelestia) instead. + +### Package manager + +> [!NOTE] +> If you want to make your own changes/tweaks to the shell do NOT edit the files installed by the AUR +> package. Instead, follow the instructions in the [manual installation section](#manual-installation). + +The shell is available from the AUR as `caelestia-shell-git`. You can install it with an AUR helper +like [`yay`](https://github.com/Jguer/yay) or manually downloading the PKGBUILD and running `makepkg -si`. + +### Manual installation + +Dependencies: + +- [`caelestia-cli`](https://github.com/caelestia-dots/cli) +- [`quickshell-git`](https://quickshell.outfoxxed.me) - this has to be the git version, not the latest tagged version +- [`ddcutil`](https://github.com/rockowitz/ddcutil) +- [`brightnessctl`](https://github.com/Hummer12007/brightnessctl) +- [`app2unit`](https://github.com/Vladimir-csp/app2unit) +- [`cava`](https://github.com/karlstav/cava) +- [`networkmanager`](https://networkmanager.dev) +- [`lm-sensors`](https://github.com/lm-sensors/lm-sensors) +- [`fish`](https://github.com/fish-shell/fish-shell) +- [`curl`](https://github.com/curl/curl) +- [`aubio`](https://github.com/aubio/aubio) +- [`libpipewire`](https://pipewire.org) +- `glibc` +- `qt6-declarative` +- `gcc-libs` +- [`material-symbols`](https://fonts.google.com/icons) +- [`jetbrains-mono-nerd`](https://www.nerdfonts.com/font-downloads) +- [`grim`](https://gitlab.freedesktop.org/emersion/grim) +- [`swappy`](https://github.com/jtheoof/swappy) +- [`libqalculate`](https://github.com/Qalculate/libqalculate) + +To install the shell manually, install all dependencies and clone this repo to `$XDG_CONFIG_HOME/quickshell/caelestia`. +Then compile the beat detector and install it to `/usr/lib/caelestia/beat_detector`. -The install script creates and enables the systemd service `caelestia-shell.service` which should automatically start the -shell on login. +```sh +cd $XDG_CONFIG_HOME/quickshell +git clone https://github.com/caelestia-dots/shell.git caelestia +g++ -std=c++17 -Wall -Wextra -I/usr/include/pipewire-0.3 -I/usr/include/spa-0.2 -I/usr/include/aubio -o beat_detector caelestia/assets/beat_detector.cpp -lpipewire-0.3 -laubio +sudo mv beat_detector /usr/lib/caelestia/beat_detector +``` -### Via command +## Usage -If not on a system that uses systemd, you can manually start the shell via `caelestia-shell`. -To autostart it on login, you can use an `exec-once` rule in your Hyprland config: -``` -exec-once = caelestia shell -``` +The shell can be started via the `caelestia shell -d` command or `qs -c caelestia`. +If the entire caelestia dots are installed, the shell will be autostarted on login +via an `exec-once` in the hyprland config. ### Shortcuts/IPC All keybinds are accessible via Hyprland [global shortcuts](https://wiki.hyprland.org/Configuring/Binds/#dbus-global-shortcuts). -For a preconfigured setup, install [`caelestia-hypr`](https://github.com/caelestia-dots/hypr) via `caelestia install hypr` or see -[this file](https://github.com/caelestia-dots/hypr/blob/main/hyprland/keybinds.conf#L1-L29) for an example on how to use global -shortcuts. +If using the entire caelestia dots, the keybinds are already configured for you. +Otherwise, [this file](https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland/keybinds.conf#L1-L39) +contains an example on how to use global shortcuts. All IPC commands can be accessed via `caelestia shell ...`. For example + ```sh caelestia shell mpris getActive trackTitle ``` -The list of IPC commands can be shown via `caelestia shell help`: +The list of IPC commands can be shown via `caelestia shell -s`: + ``` -> caelestia shell help +$ caelestia shell -s +target drawers + function toggle(drawer: string): void + function list(): string +target notifs + function clear(): void +target lock + function lock(): void + function unlock(): void + function isLocked(): bool target mpris + function playPause(): void + function getActive(prop: string): string + function next(): void function stop(): void function play(): void - function next(): void - function getActive(prop: string): string function list(): string - function playPause(): void function pause(): void function previous(): void -target drawers - function list(): string - function toggle(drawer: string): void +target picker + function openFreeze(): void + function open(): void target wallpaper - function list(): string - function get(): string function set(path: string): void -target notifs - function clear(): void + function get(): string + function list(): string ``` ### PFP/Wallpapers -The profile picture for the dashboard is read from the file `~/.face`, so to set it just put your image there. +The profile picture for the dashboard is read from the file `~/.face`, so to set +it you can copy your image to there or set it via the dashboard. -The wallpapers for the wallpaper switcher are read from `~/Pictures/Wallpapers`, so put your wallpapers there for -them to show up in the switcher (you need to restart the shell after changing stuff in `~/Pictures/Wallpapers` sadly, -no watching for changes yet). +The wallpapers for the wallpaper switcher are read from `~/Pictures/Wallpapers` +by default. To change it, change the wallpapers path in `~/.config/caelestia/shell.json`. To set the wallpaper, you can use the command `caelestia wallpaper`. Use `caelestia wallpaper -h` for more info about the command. +## Updating + +If installed via the AUR package, simply update your system (e.g. using `yay`). + +If installed manually, you can update by running `git pull` in `$XDG_CONFIG_HOME/quickshell/caelestia`. + +```sh +cd $XDG_CONFIG_HOME/quickshell/caelestia +git pull +``` + +## Configuring + +All configuration options are in `~/.config/caelestia/shell.json`. The config +currently gets overwritten on startup however due to an upstream bug with Quickshell. + ## Credits Thanks to the Hyprland discord community (especially the homies in #rice-discussion) for all the help and suggestions @@ -110,7 +156,8 @@ Another special thanks to [@end_4](https://github.com/end-4) for his [config](ht which helped me a lot with learning how to use Quickshell. Finally another thank you to all the configs I took inspiration from (only one for now): -- [Axenide/Ax-Shell](https://github.com/Axenide/Ax-Shell) + +- [Axenide/Ax-Shell](https://github.com/Axenide/Ax-Shell) ## Stonks 📈 -- cgit v1.2.3-freya